素材（Assets）

通用信息

• Base URL：https://api.routeapi.ai
• 认证：Authorization: Bearer $ROUTEAPI_KEY，使用 sk- 开头的 API Key（在控制台 API Keys 页面创建）。rat_ 开头的管理密钥不能调用模型。
• 错误格式：这些端点上 RouteAPI 自身的错误使用 {"error": "..."} 或 {"error": "...", "code": "..."}；被共享认证或限流中间件拒绝的请求则可能返回 {"error": {"message": "...", "type": "error", "code": "..."}}。上游状态码与响应体原样透传。详见下文限制与错误与常见错误。

资产 API 用于存储参考素材——图像、视频、音频——供 Seedance 视频模型作为输入使用。素材只需添加一次，等上游资产服务处理完成，之后在视频生成请求中用 asset://<asset_id> 引用它，而不必每次都传入同一个公网 URL。

这是一个管理类 API，不是生成类 API。RouteAPI 用你的 API Key 完成调用认证，转发到上游资产服务，并返回上游的响应。这些端点上的调用不按模型用量计费。它们也不在 OpenAI SDK 的覆盖范围内，因此请使用原生 HTTP 调用，而不是 SDK 客户端。

请求与响应体原样转发

RouteAPI 不会重塑资产请求体。除下方的体积限制和特殊处理之外，请求体与响应体 均原样透传，所以这里展示的字段集合就是上游契约。请勿将确切的响应字段集合 视为固定不变。

工作流

1. 创建资产组：POST /v1/asset-groups。
2. 添加资产到该组：POST /v1/assets，传入一个可公网下载的 URL。
3. 轮询资产：GET /v1/assets/{assetID}，直到状态变为 Active。处理是异步的。
4. 引用资产：在 POST /v1/video/generations 请求的 metadata.content 中以 asset://<asset_id> 引用它。参见在 Seedance 请求中使用资产和 Seedance。
5. 照常轮询视频任务。基于资产的视频请求只会向上游发送一次，不会重试，也不会故障转移到其他渠道。

端点

方法	路径	用途	是否分配资产空间
POST	/v1/asset-groups	创建资产组	是
GET	/v1/asset-groups	列出资产组	否
GET	/v1/asset-groups/{groupID}	获取单个资产组	否
DELETE	/v1/asset-groups/{groupID}	删除资产组	否
PUT	/v1/asset-groups/{groupID}	重命名资产组	否
POST	/v1/assets	向资产组添加资产	是
GET	/v1/assets	列出资产组中的资产	否
GET	/v1/assets/{assetID}	获取单个资产（用于轮询）	否
DELETE	/v1/assets/{assetID}	删除资产	否
PUT	/v1/assets/{assetID}	重命名资产	否
POST	/v1/assets/verify-sessions	创建真人核验会话	是
GET	/v1/assets/verify-sessions/{sessionID}	获取核验会话	否

认证方式

在标准请求头中传入 Model API Key：

Authorization: Bearer sk-your-routeapi-key

该 Key 标识 RouteAPI 账户。资产按账户隔离：同一账户下的每个 API Key 看到的是相同的资产组、资产和核验会话，其他账户则看不到它们。该 Key 绝不会被发送到上游——RouteAPI 会代替你使用独立的上游凭证。

首次使用与资产池凭证

每个账户绑定一个上游凭证，资产服务用它来隔离该账户的素材。账户第一次调用创建类端点时会自动分配：

• POST /v1/asset-groups
• POST /v1/assets
• POST /v1/assets/verify-sessions

一旦分配，该绑定对账户永久有效，后续每次调用都会复用，包括引用 asset:// 资产的视频请求。

读取和删除类端点从不分配。绑定建立之前：

调用	响应
GET /v1/asset-groups	200，空列表：{"total": 0, "asset_groups": []}
其他任何 GET 或 DELETE	404，{"error": "not found"}

也就是说，空资产组列表对新账户来说是正常结果；而首次使用之前对某个具体资产或资产组返回 404，含义是「该账户尚无资产空间」，而不是「ID 有误」。

资产组到凭证的路由属于服务端配置细节。如果所属分组未配置资产渠道，第一次创建类调用会以 503 asset_pool_exhausted 或 503 asset_pool_misconfigured 失败，而不是分配凭证。稍后重试；若持续出现，请联系支持。

故障凭证将停用

如果上游以 401 拒绝你的凭证，RouteAPI 会将绑定标记为故障，并返回 503 asset_key_unavailable。此后所有资产调用——以及每个引用资产的视频请求—— 都会持续返回该错误码，直到管理员恢复绑定。因此在生产环境中依赖此路径之前， 请先在测试环境验证。

资产组

创建资产组

POST /v1/asset-groups

curl https://api.routeapi.ai/v1/asset-groups \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-refs",
    "description": "Reference material for product videos"
  }'

字段	类型	必填	说明
name	string	是	资产组名称
description	string	否	资产组描述

响应：

{
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "name": "product-refs",
  "project_name": "default",
  "status": "active"
}

请保存 asset_group_id：添加资产时必须使用它。

列出资产组

GET /v1/asset-groups

curl "https://api.routeapi.ai/v1/asset-groups?page=1&page_size=20" \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

page、page_size 等分页参数会原样转发；上游服务的默认值与单页上限同样适用。

{
  "total": 1,
  "asset_groups": [
    {
      "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
      "group_type": "AIGC",
      "project_name": "default",
      "session_id": "",
      "status": "active",
      "created_at": 1792050332,
      "updated_at": 1792050332
    }
  ]
}

session_id 仅在通过真人核验创建的资产组中才有值。已核验真人的资产组 group_type 为 LivenessFace；普通资产组为 AIGC。

获取单个资产组

curl https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

上游的详情响应可能返回空字符串 status。需要判断资产组是否可用时，请使用列表响应或创建响应中的值。

删除资产组

curl -X DELETE https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{ "deleted": "local_group_2c8186e6d8b44ffa73b371677bfe4af2" }

删除不可恢复。

重命名资产组

curl -X PUT https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "new_group_name"}'

{ "name": "new_group_name", "updated": "local_group_2c8186e6d8b44ffa73b371677bfe4af2" }

资产

添加资产

POST /v1/assets

每次请求添加一个资产。传入所属资产组、名称，以及且仅一个来源 URL。

字段	类型	必填	说明
asset_group_id	string	是	资产所属的资产组
asset_name	string	是	仅用于查找的名称；不影响生成
image_url	string	三选一	图片的公网 URL
video_url	string	三选一	视频的公网 URL
audio_url	string	三选一	音频文件的公网 URL
asset_type	string	否	Image、Video 或 Audio；省略时根据 URL 字段推断
description	string	否	资产描述

image_url、video_url、audio_url 必须且只能传入一个；传入零个或多个时上游服务会拒绝请求。该 URL 必须能在公网上下载，无需认证或额外请求头。不支持 Base64 载荷和内网地址，并且在处理完成前该 URL 必须保持可访问。

curl https://api.routeapi.ai/v1/assets \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
    "asset_name": "product-front",
    "image_url": "https://cdn.example.com/product-front.jpg"
  }'

{
  "asset_id": "local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "asset_name": "product-front",
  "asset_type": "Image",
  "asset_uri": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "status": "Processing"
}

创建成功只表示请求已被接受，并不表示资产已可用。asset_uri 才是视频请求中应使用的形式。

资产状态

状态	含义	下一步
Processing	仍在摄取中	继续轮询
Active	可以使用	在视频请求中引用它
Failed	摄取失败	检查格式和体积要求，然后重新添加

获取单个资产

此端点用于轮询，每 5–10 秒一次，并设置总超时。处理通常需要数秒到数十秒；视频资产和高峰期会更久。

curl https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{
  "asset_id": "local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "status": "Active",
  "asset_uri": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "url": "https://..."
}

url 是临时的签名下载地址。不要存储它；生成时请使用 asset_uri。

资产不存在或已被删除时，上游服务返回 404，例如：

{ "details": "record not found", "error": "asset not found in database" }

列出与删除资产

# 列出 —— asset_group_id 为必填
curl "https://api.routeapi.ai/v1/assets?asset_group_id=local_group_2c8186e6d8b44ffa73b371677bfe4af2" \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

# 删除
curl -X DELETE https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{ "deleted": "local_asset_25e4d0cb018fb5802bf4e466f99707d0" }

删除资产会导致所有引用它的新视频请求失败。

重命名资产

curl -X PUT https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "new_asset_name"}'

{ "updated": "local_asset_25e4d0cb018fb5802bf4e466f99707d0" }

改名后，资产详情和列表中的名称返回新值。

真人核验会话

包含真人面部的参考素材，需要先取得本人同意。核验会话会为该人的素材生成一个专用资产组；添加到其中的资产会进行人脸一致性校验。

创建会话

POST /v1/assets/verify-sessions

请求体可以为空（{} 或完全不带请求体）。callback_url 可接受，但不用于跳转。

curl https://api.routeapi.ai/v1/assets/verify-sessions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "session_id": "asset_sess_5e7860e76613dd51a4867bdcbea6076b",
  "status": "pending",
  "h5_link": "https://...one-time-link...",
  "callback_url": ""
}

h5_link 只能发送给将要接受核验的本人。它包含一次性凭证，可访问核验页面；不要把它放进公开日志、截图或群聊。

获取会话

curl https://api.routeapi.ai/v1/assets/verify-sessions/asset_sess_5e7860e76613dd51a4867bdcbea6076b \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

status	含义
pending	等待本人操作，或仍在处理中
succeeded	核验成功；asset_group_id 已填充
failed	核验失败；请读取 error

{
  "session_id": "asset_sess_a8af6fab34f694ada40c22521448f579",
  "status": "succeeded",
  "result_code": "",
  "error": "",
  "asset_group_id": "group-20261015202316-4t5jt",
  "project_name": "default",
  "created_at": 1792066965,
  "updated_at": 1792067203
}

没有回调到你的服务的 webhook 或跳转——本人的浏览器最终停留在上游提供的结果页。请轮询会话直到 status 变为 succeeded（通常在几分钟内），然后把该人的素材添加到返回的 asset_group_id 中。result_code 目前始终为空；请使用 status。若会话 status 为 failed 且 error 形如 verification expired，必须重新创建。

在 Seedance 请求中使用资产

在视频生成请求的 metadata.content 中引用资产，使用资产 API 返回的 asset_uri：

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "The product in image 1 rotates slowly",
    "metadata": {
      "content": [
        { "type": "text", "text": "The product in image 1 rotates slowly" },
        {
          "type": "image_url",
          "image_url": { "url": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0" },
          "role": "reference_image"
        }
      ],
      "duration": 4,
      "resolution": "480p",
      "ratio": "1:1"
    }
  }'

请从 GET /v1/models 中选择支持视频生成的 Seedance 模型 ID；参见模型。Seedance 的请求格式，包括 metadata.content 的 role 用法和各模型限制，记录在 Seedance 中。

以下规则来自资产服务的契约：

• type/role 组合必须与资产类型匹配：image_url 配 reference_image，video_url 配 reference_video，audio_url 配 reference_audio。
• 只有 Active 状态的资产才能被引用。
• 提示词通过序号引用素材（“image 1”、“video 1”），序号按 content 顺序在各类型内部计数。不要在提示词中写入资产 ID。
• 真人素材必须来自已核验的资产组；否则上游可能会拒绝请求或使任务失败。

RouteAPI 通过查找任何以 asset:// 开头的 JSON 字符串值来识别引用（不区分大小写）。此类请求会被固定到你的资产渠道并只发送一次，不重试、不做渠道故障转移。以下情况下，请求会在本地被拒绝：

状态	错误码	原因
400	asset_key_required	请求体引用了 asset://，但该账户尚无资产空间。请先创建资产组和资产
400	asset_remix_conflict	对非资产任务做 remix 时试图引用 asset:// 资产
400	asset_channel_conflict	该 API Key 被固定到某个特定渠道，而该渠道不是你的资产渠道
400	asset_model_unsupported	你的资产渠道不支持该模型
503	asset_key_unavailable	绑定到该账户的上游凭证处于故障或被禁用状态

这些错误使用任务错误结构 {"code": ..., "message": ..., "data": ...}。

限制与错误

• 请求体 — POST 和 PUT 请求体按 1 MiB 上限读取。超出上限时会在发送到上游之前返回 413。素材本身从不通过请求体上传；请传入 URL。
• 请求体形态 — 非空的 POST 或 PUT 请求体必须是 JSON 对象。数组、裸字符串、null 以及非法 JSON 都会返回 400，且不会到达上游服务。GET 和 DELETE 的请求体被忽略。
• 改名请求体 — PUT 请求体必须带非空字符串字段 name（字段名小写）。缺少该字段、值为空或不是字符串时返回 400，且不会到达上游服务。
• 响应体 — 上游响应超过 10 MiB，或读取失败的响应，返回 502。
• 超时 — 上游调用有固定的 60 秒超时；超时会以 502 报告。
• project_name — 如果出现在 POST 或 PUT 请求体中，该字段会在转发前被移除，无论字母大小写。
• 归属错误 — 如果上游以 403 返回归属拒绝（“you do not own” / “access denied”），RouteAPI 会改为返回 404 {"error": "not found"}，使该资源看起来不存在而不是无权限。
• 上游凭证故障 — 上游 401 会变成 503 asset_key_unavailable，并将账户绑定标记为故障（见上文）。上游 402，或响应体看起来像计费问题的上游错误，会变成 503 asset_service_unavailable。

其他上游状态码和响应体会原样透传，包括上游参数校验错误。RouteAPI 自身的错误使用以下三种结构之一：

{ "error": "not found" }

{ "error": "<message>", "code": "asset_pool_busy" }

{
  "error": {
    "message": "token.invalid (request id: ...)",
    "type": "error",
    "code": ""
  }
}

第三种结构来自共享的认证与限流中间件，因此请先判断 error 是字符串还是对象。本地 message 文案目前为中文——对于前两种结构，请依据 HTTP 状态码和 code 字段分支处理，而不要依赖 message。

状态	错误码	含义	处理
400	—	请求体不是 JSON 对象，或上游拒绝了参数	修正请求；不要原样重试
401	—	API Key 缺失、无效或已删除	检查 Authorization
404	—	未知的资产、资产组或会话；或该账户尚无资产空间	检查 ID；若是新账户请先创建资产组
413	—	请求体超过 1 MiB	改为传 URL，而不是内联数据
429	—	触发限流	放慢轮询频率并稍后重试
500	asset_pool_internal_error	RouteAPI 无法读写自身的资产状态	稍后重试
500	—	RouteAPI 在读取账户资产状态时失败	稍后重试
502	—	上游不可达、超时，或返回了无法读取/过大的响应	稍后重试
503	asset_key_unavailable	账户的上游凭证处于故障或被禁用状态	联系支持；重试无效
503	asset_pool_exhausted	所属分组没有资产渠道，或没有可分配的凭证	稍后重试或联系支持
503	asset_pool_busy	存在凭证，但当前无法分配任何一个	稍后重试
503	asset_pool_misconfigured	所属分组映射到多个资产渠道	联系支持
503	asset_channel_unavailable	资产渠道本身被禁用或配置错误	稍后重试或联系支持
503	asset_service_unavailable	上游账户余额不足或硬性故障	稍后重试或联系支持

资产调用不产生模型费用，但当平台启用模型请求速率限制时，它们会像其他任何 /v1 请求一样计入限制。通用错误模型参见常见错误，消耗这些资产的视频生成如何计费参见模型定价。

接下来

• Seedance — Seedance 请求格式与 metadata.content 的 role 用法。
• 创建视频生成任务 — 所有视频模型共用的通用请求格式。
• 模型 — 查找受支持的视频模型 ID。
• 常见错误 — 状态码与排查顺序。