👩💻 虚拟人像（Avatar）资产管理

虚拟人像（如特定装扮的人物、微调后的 IP 角色）由于其高度的版权及肖像安全要求，直接通过公网 URL 往往会被最新一代防 Deepfake 视频模型（如 Seedance 2.0）作为风险予以拦截。

要让模型根据你的指定人物生成视频，必须先将形象图片上传到私域资产库。

图片格式最佳要求

为了让生成效果最好，建议你上传的虚拟人像源图满足以下条件：

格式: jpeg、png、webp 等主流图片
宽高比: (0.4 到 2.5 之间)
分辨率: 短边/长边建议在 300px 到 6000px 之间，推荐 1080p
大小: 单图 < 30MB

入库完整链路

如果您是一名开发者，需要通过代码实现素材的自动流转入库，无需再关注底层供应商（如火山引擎）复杂的 AK/SK 鉴权规则及繁琐的轮询逻辑。AILB 网关提供了一套零感知的无缝托管方案。

1. 发起上传

现在您可以直接使用与 OpenAI 完全兼容的 /v1/files 标准接口。不管是通过原生 OpenAI SDK 还是 HTTP API，均能提取并获取到标准的 File 对象：

使用官方 Python OpenAI SDK 发送

from openai import OpenAI

client = OpenAI(
    base_url="https://ailb.5884.cn/v1",
    api_key="sk-您的AILB令牌"
)

# 使用标准文件上传即可
file_response = client.files.create(
    file=open("your-avatar.jpg", "rb"),
    purpose="vision",
)

# 你将直接获得一串 AILB 的跨渠道统一资源标识作为 ID：
# 此处的 file_response.id 类似于 "asset://ma_12345"
print(file_response.id)

对于直接使用 HTTP 接口调用的开发者，该 POST /v1/files 端点的标准的 JSON 返回结构如下：

文件上传后的标准 OpenAI File 返回值

{
  "id": "asset://ma_23",
  "object": "file",
  "bytes": 204800,
  "created_at": 1712130000,
  "filename": "your-avatar.jpg",
  "purpose": "vision",
  "status": "uploaded"
}

2. 状态查询与进度感知

鉴于底层的火山引擎对于图片筛查存在 10 到 30 秒的异步入库排队流程，上传操作不会阻塞进程，而是交由 AILB 后台静默组装传输与轮询审核。您随时可以通过标准的查询文件动作监听底层的入库进展：

查询素材审核状态并获取真实上游 ID

import time

file_meta = client.files.retrieve(file_response.id)
print("初始状态:", file_meta.status)

# 【高阶用法 - 不推荐】
# AILB 网关提供全网独有的 15秒智能无感知轮询，强烈建议您直接将 file_response.id 传给下游生视频模型！
# 若由于特殊定制需求，您坚决不使用网关轮询，并需要自己提取底层原生火山引擎的 ID，您可以如下操作（注意：手动轮询会增加带宽高并发，请限制重试次数）：

# 使用 for 循环安全重试获取，最多常试 10 次
for i in range(10):
    if file_meta.status != "uploaded":
        break
        
    time.sleep(2)  # 等待 2 秒
    file_meta = client.files.retrieve(file_response.id)
    print(f"第 {i + 1} 次检查状态...", file_meta.status)

if file_meta.status == "processed":
    # 获取原生火山引擎 ID (例如 "Asset://xxx")
    # 提示：由于 openai 官方 python 库模型严格，额外参数可能需要 dump() 获取
    real_volcano_id = file_meta.model_dump().get("volc_asset_uri", "") 
    print("获取成功，您可直接将此 ID 喂给接下来的大模型：", real_volcano_id)
else:
    error_details = file_meta.model_dump().get("status_details", file_meta.status)
    print("处理超时或失败，最终状态:", error_details)

如果您使用纯 HTTP 请求 GET /v1/files/asset://ma_23（或者 ma_23）去轮询，审核成功后您将获得的 JSON 结构如下：

轮询成功的状态查询返回值

{
  "id": "asset://ma_23",
  "object": "file",
  "bytes": 204800,
  "created_at": 1712130000,
  "filename": "your-avatar.jpg",
  "purpose": "vision",
  "status": "processed",
  "volc_asset_uri": "Asset://asset-12345"
}

其中 volc_asset_uri 即为跨维免审传递给模型的最底层真实资产凭证。

3. 在视频生成中使用资产

对客户端而言，你可以在获得 ID 后，不用等待异步结束，立刻无缝地通过标准的 OpenAI 格式将其交由模型处理。这是因为网关会在内部为您自动挂起请求（最多软阻塞 15 秒）来轮询火山过审状态，彻底消灭前端复杂的轮询代码！

当使用 Seedance 2.0 及其他被风控模型时： 在您通常传入图片 url 的结构处，直接替换为您刚刚拿到的 asset://ma_xxx。

AILB 网关多模态 Video Completions Payload

{
  "model": "doubao-seedance-2-0",
  "prompt": "填写任意内容，不实际用到（会被 metadata.content 覆盖，但因网关基础校验必传）",
  "metadata": {
    "generate_audio": true,
    "ratio": "16:9",
    "duration": 11,
    "watermark": false,
    // 重点：大厂专有模型的特定生成控制参数（如比例、时长），在 AILB 网关统一包裹在 metadata 节点中透传！
    // 并且如果提供了下方的 content 结构，其将会完全代替掉外层的 dummy prompt。
    // 视频和音频目前请传入公网可访问的真实 URL
    "content": [
      {
        "type": "text",
        "text": "全程使用视频1的第一视角构图，全程使用音频1作为背景音乐。第一人称视角果茶宣传广告，seedance牌「苹苹安安」苹果果茶限定款；首帧为图片1...杯身标签清晰可见，尾帧定格为图片2。背景声音统一为女生音色。"
      },
      {
        "type": "image_url",
        "image_url": {
          // 直接填入您刚刚获取到的 AILB 统一资产前缀（无感轮询）
          // 或是您获取的原生真实 ID ("Asset://xxx") 均可，网关会自动分发映射！
          "url": "asset://ma_pic_123"
        },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ma_pic_456"
        },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {
            // 视频和音频目前请传入公网可访问的真实 URL
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
        },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
        },
        "role": "reference_audio"
      }
    ]
  }
}

4. 轮询 task_id 获取结果

如果在底层生成耗时较久，网关会自动将此请求转化为异步任务，并在当前的请求中立即向你返回一个 task_id（类似于 seedance-t-xxxx）。

拿到此 task_id 后，你需要通过标准的 GET /v1/video/generations/{task_id} 接口进行循环获取任务进度并最终拿到视频结果。

轮询获取最终生成结果

import time
import requests

API_KEY = 'sk-your_key_here'
TASK_ID = '这里填写你刚获取的 task_id'
URL = f'https://ailb.5884.cn/v1/video/generations/{TASK_ID}'
HEADERS = {'Authorization': f'Bearer {API_KEY}'}

while True:
    response = requests.get(URL, headers=HEADERS)
    result = response.json()
    status_data = result.get('data', {})
    status = status_data.get('status')
    print(f"当前进度与状态: {status}")
    
    if status == 'SUCCESS':
        print(f"✅ 生成成功！下载链接: {status_data.get('result_url')}")
        break
    elif status in ['FAILURE', 'FAILED', 'CANCELED']:
        print("❌ 内部任务被驳回或失败")
        break
        
    time.sleep(5) # 每 5 秒轮询一次最佳

AILB 自动无感处理倒数与智能降级

无感等待：在调用模型生成时，若该素材仍处于火山的排队审核期间（通常需 3-10 秒），AILB 会在网关底层替您自动阻塞重试，一旦成功即刻释放。
专线直输：若素材已经完成合规，资产引用的请求在发往火山前会被拦截并无缝换绑为底层免流免检的专用协议（如 Asset://xxx），实现极速生视频。
智能降级：若是发送给那些不支持私有协议的模型（或者发生不可抗异常），系统均会稳妥地把它降级解析回有效期四小时的腾讯云临时直链签名（Signed COS URL），保证任意模型都可兜底完成供给渲染。

虚拟人像素材管理最佳实践