AIin1Portal

资产库(虚拟人像)

POST /v1/assets · GET /v1/assets · GET /v1/assets/{id} · DELETE /v1/assets/{id}

海外线路(-hw 系列)的 Seedance 视频支持虚拟人像资产库:把一张人像图上传成一个资产,得到 asset://<资产 ID>,之后在视频生成请求里用它作为人物/角色参考,保证生成视频中人物的脸、服饰等特征一致。

组织私有 + 隔离:你上传的资产只属于你的组织,只有你能引用;别的组织即使拿到你的 asset:// ID 也无法使用,查询列表也只会看到自己的资产。

仅虚拟人像:资产库只接受合成/虚拟人像,素材不得像真实自然人(上游会审核,像真人的会被拒)。

1. 上传资产:POST /v1/assets

两种上传方式,二选一:

1.1 方式 A:直接上传图片文件(multipart/form-data,推荐)

字段 类型 必填 说明
file file 是 图片文件。格式 jpeg / png / webp / bmp / tiff / gif / heic;宽高比 (0.4, 2.5);宽高 300–6000px;< 30 MB。
name string 否 资产名称,便于自己管理(不参与生成)。 
curl https://api.portal.aiin1.ai/v1/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@portrait.jpg" \
  -F "name=主角-小美"

1.2 方式 B:提供公网图片 URL(application/json)

字段 类型 必填 说明
source_url string 是 可公开访问的 http(s) 图片 URL(上游需要能拉取到)。
name string 否 资产名称。 
curl https://api.portal.aiin1.ai/v1/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source_url": "https://example.com/portrait.jpg", "name": "主角-小美" }'

1.3 返回

上传是异步预处理(上游审核+入库,通常约 10 秒)。接口会内联等待一小段:

  • 预处理已完成 → 200,status: "active"(可立即用于生成)。
  • 仍在处理 → 202,status: "processing"(稍后用查询轮询到 active)。
  • 审核失败 → 200,status: "failed",并带 fail_reason。
{
  "id": "asset-20260722081357-abcde",
  "asset": "asset://asset-20260722081357-abcde",
  "status": "active",
  "name": "主角-小美",
  "asset_type": "Image"
}
字段 说明
id 资产 ID。
asset 可直接粘贴进视频请求 image_url / reference_image_urls 的引用串。
status processing / active / failed。只有 active 能用于生成。

只有 status=active 的资产能在视频请求里引用;processing / failed 的会被视频接口以 400 拒绝。

2. 查询资产:GET /v1/assets/{id}

按 ID 查单个资产;若仍在 processing 会自动刷新一次最新状态。

curl https://api.portal.aiin1.ai/v1/assets/asset-20260722081357-abcde \
  -H "Authorization: Bearer YOUR_API_KEY"
{ "id": "asset-20260722081357-abcde", "asset": "asset://asset-20260722081357-abcde", "status": "active", "name": "主角-小美", "asset_type": "Image", "created_at": "2026-07-22T08:13:57+00:00" }

非本组织的资产返回 404。

3. 列出资产:GET /v1/assets

列出本组织的全部资产(不含已删除),按创建时间倒序。

curl https://api.portal.aiin1.ai/v1/assets \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "object": "list",
  "data": [
    { "id": "asset-20260722081357-abcde", "asset": "asset://asset-20260722081357-abcde", "status": "active", "name": "主角-小美", "asset_type": "Image", "created_at": "2026-07-22T08:13:57+00:00" }
  ]
}

4. 删除资产:DELETE /v1/assets/{id}

curl -X DELETE https://api.portal.aiin1.ai/v1/assets/asset-20260722081357-abcde \
  -H "Authorization: Bearer YOUR_API_KEY"
{ "id": "asset-20260722081357-abcde", "deleted": true }

非本组织的资产返回 404。

5. 在视频里使用资产

拿到 active 的 asset://<id> 后,放进视频生成请求的 image_url(单个)或 reference_image_urls(多个),model 必须是 -hw 海外线路名,并在 prompt 里按 @Image1 / @Image2 序号指代(不要写 asset ID):

curl https://api.portal.aiin1.ai/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-hw",
    "prompt": "@Image1 的人像在咖啡厅里对着镜头微笑挥手,自然光",
    "seconds": "5",
    "size": "1280x720",
    "reference_image_urls": ["asset://asset-20260722081357-abcde"]
  }'

6. 常见错误

HTTP 场景 说明
400 缺 file / source_url 二者必须提供其一。
400 图片类型不支持 仅 jpeg / png / webp / bmp / tiff / gif / heic。
400 视频引用了不属于你的资产 asset:// 必须是本组织已上传且 active 的资产;否则视频接口 400。
401 API Key 无效 检查 Authorization 头。
404 资产不存在 / 非本组织 查询/删除的 ID 错误或不属于你的组织。
413 图片过大 单图 < 30 MB。
503 资产库不可用 你的组织未开通海外(-hw)线路,或存储暂不可用。