LLMGateway

Appearance

视频素材库 ​

视频素材库为图片、视频和音频输入提供租户内稳定的 llmgw_asset:// URI。客户请求不需要感知火山方舟或其他供应商的素材 ID；平台会在视频任务选定渠道后转换成该供应商支持的 URL 或私域素材 URI。

接口使用 API Key 鉴权：

text
Base URL: https://llm.xiaoyue9527.xyz/v1
Authorization: Bearer sk-gtw-REPLACE_ME
Content-Type: application/json

接口 ​

接口方法用途
/v1/assetsPOST新增素材
/v1/assetsGET查询当前租户素材
/v1/assets/capabilitiesGET查询当前环境可用的素材能力
/v1/assets/groupsPOST创建 Ark 虚拟人或真人素材组
/v1/assets/groupsGET查询素材组
/v1/assets/groups/{group_id}/verification-sessionsPOST为真人素材组发起 H5 活体认证
/v1/assets/groups/{group_id}/verification-sessions/{session_id}GET查询真人认证状态
/v1/assets/groups/{group_id}DELETE删除空素材组
/v1/assets/{asset_id}GET查询单个素材
/v1/assets/{asset_id}PATCH修改素材名称
/v1/assets/{asset_id}/syncPOST同步 Ark 私域素材状态
/v1/assets/{asset_id}DELETE删除素材
/v1/files/uploadsPOST创建素材文件上传会话
/v1/files/uploads/{upload_id}/completePOST完成上传并触发文件校验
/v1/files/{file_id}GET查询素材文件校验状态
/v1/files/{file_id}/download-urlPOST创建短期下载地址
/v1/files/{file_id}DELETE删除未被素材引用的文件

普通素材、虚拟人素材和通过 H5 激活的真人素材可由同一租户内的 API Key 使用。企业协议真人素材的列表仍是租户级可见，但创建素材及用于生成的权限按当前 API Key 单独授权，不能仅凭同租户关系使用。其他租户使用素材 ID 查询或生成时统一返回 asset_not_found。

/v1/files/uploads 等是视频素材专用的受管文件接口，不是标准 OpenAI Files API，不能用 client.files.create() 或 client.files.list() 替代。标准 OpenAI GET /v1/files、POST /v1/files 当前仍未开放。

新增 HTTPS 素材 ​

当前开放受控 HTTPS 素材。URL 必须能被视频供应商访问，且不能是 localhost、内网地址或包含账号密码。

bash
curl -X POST https://llm.xiaoyue9527.xyz/v1/assets \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "产品首帧",
    "media_type": "image",
    "source": {
      "type": "url",
      "url": "https://cdn.example.com/video-assets/product-frame.png"
    },
    "rights_attestation": {
      "accepted": true,
      "terms_version": "video-asset-rights-v1"
    }
  }'

成功返回：

json
{
  "id": "ast_123",
  "object": "video.asset",
  "uri": "llmgw_asset://ast_123",
  "name": "产品首帧",
  "asset_type": "generic",
  "media_type": "image",
  "status": "active",
  "source_kind": "external_url",
  "version": 1
}

平台响应不会回传原始 URL。rights_attestation.accepted 必须为 true，用于确认调用方拥有素材的合法使用权。

Ark 官方虚拟人素材 ​

调用 /v1/assets/capabilities 后，仅当 ark_virtual_person_create_enabled=true 时才可创建 Ark 私域虚拟人素材。 AK/SK 已配置只代表控制面签名可用；若账号尚未开通对应创作权益，该字段为 false，创建接口返回 asset_provider_subscription_required。充值账户余额不会自动开通该权益。

先创建一个虚拟人素材组：

bash
curl -X POST https://llm.xiaoyue9527.xyz/v1/assets/groups \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "品牌虚拟角色",
    "description": "已获得商业生成授权",
    "asset_type": "virtual_person",
    "rights_attestation": {
      "accepted": true,
      "terms_version": "video-asset-rights-v1"
    }
  }'

使用返回的 id 创建 Ark 私域素材：

bash
curl -X POST https://llm.xiaoyue9527.xyz/v1/assets \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "角色正面照",
    "asset_type": "virtual_person",
    "group_id": "astgrp_REPLACE_ME",
    "media_type": "image",
    "source": {
      "type": "url",
      "url": "https://cdn.example.com/video-assets/character.png"
    },
    "rights_attestation": {
      "accepted": true,
      "terms_version": "video-asset-rights-v1"
    }
  }'

新素材先返回 processing。稍后同步状态：

bash
curl -X POST https://llm.xiaoyue9527.xyz/v1/assets/ast_REPLACE_ME/sync \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME'

只有 active 素材可用于视频任务。客户响应不会包含 Ark 上游 group ID、asset ID、控制面凭据或原始 URL。

Ark 官方真人素材 ​

真人素材用于上传本人图片、视频或音频。每个真人素材组只对应一位本人；除企业协议授权模式外，必须先由本人完成 Ark 官方 H5 活体认证。活体采集与核验均在 Ark H5 页面完成；平台不接收或保存活体原始图片、视频，也不单独暴露身份证件或原始活体人脸上传接口。

1. 检查真人能力 ​

先查询能力：

bash
curl https://llm.xiaoyue9527.xyz/v1/assets/capabilities \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME'

H5 认证模式下的关键字段如下；managed_file_rules 仅节选与真人视频匹配的一条，实际响应还可能包含其他素材与媒体类型规则：

json
{
  "real_person_enabled": true,
  "real_person_effective_mode": "required",
  "real_person_agreement_group_mode": "admin_import",
  "real_person_next_action": "complete_h5_liveness",
  "managed_file_source_enabled": true,
  "managed_file_rules": [
    {
      "asset_type": "real_person",
      "media_type": "video",
      "module": "video",
      "purpose": "ark_real_video",
      "sensitivity": "biometric",
      "max_size_bytes": 52428800,
      "mime_types": ["video/mp4"],
      "requires_media_probe": false
    }
  ]
}

不要根据 supported_asset_types 推断真人能力是否已经可用；该字段只表示接口认识的素材类型。应同时检查 real_person_enabled、real_person_effective_mode 和 real_person_next_action：

  • real_person_effective_mode=required：按下述流程创建真人素材组并完成 H5 活体认证；
  • real_person_effective_mode=agreement_exempt：当前 API Key 走企业协议授权，不自行创建素材组；当 real_person_agreement_group_mode=admin_import 时请联系平台管理员导入。能否使用以 GET /v1/assets/groups 返回的 usable_for_current_key 为准；不可用时查看 unusable_reason 并联系管理员，有效授权的到期时间见 authorization_expires_at。

企业协议仅免除 H5 活体步骤，不免除本人肖像授权、素材使用权、内容责任或平台与供应商审核。授权只对当前 API Key 生效；Key 被停用、授权到期或授权被撤销后，当前 Key 不再可在该组创建素材或使用相关素材生成，租户列表中条目仍可能可见。

2. 创建待认证真人素材组 ​

rights_attestation 必须由本人确认，且真人素材组使用独立条款版本 video-real-person-consent-v1。name 最长 64 个字符，description 最长 300 个字符：

bash
curl -X POST https://llm.xiaoyue9527.xyz/v1/assets/groups \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "本人素材",
    "description": "由本人完成活体认证",
    "asset_type": "real_person",
    "rights_attestation": {
      "accepted": true,
      "terms_version": "video-real-person-consent-v1"
    }
  }'

成功创建后返回 201，关键字段如下。此时素材组仍不可用于上传素材：

json
{
  "id": "astgrp_REPLACE_ME",
  "object": "video.asset_group",
  "asset_type": "real_person",
  "status": "pending",
  "usable_for_current_key": false
}

3. 发起本人 H5 活体认证 ​

为待认证素材组创建认证会话：

bash
curl -X POST https://llm.xiaoyue9527.xyz/v1/assets/groups/astgrp_REPLACE_ME/verification-sessions \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{}'

成功返回 201：

json
{
  "id": "vrps_REPLACE_ME",
  "object": "video.real_person_verification_session",
  "group_id": "astgrp_REPLACE_ME",
  "status": "pending",
  "launch_url": "https://llm.xiaoyue9527.xyz/r/REPLACE_ME",
  "expires_at": 1786602600,
  "created_at": 1786600800,
  "updated_at": 1786600800
}

expires_at、created_at 和 updated_at 均为 Unix 秒级时间戳。请把 launch_url 展示为二维码或在浏览器中打开，由素材本人按 Ark 页面提示完成授权和实时活体核验。认证链接有效期为 30 分钟，仅在创建会话的响应中返回；查询会话接口不会再次返回该链接。不要记录、长期保存或转发给无关人员。链接丢失、过期或认证失败后，应为同一未激活素材组（pending 或 failed）重新 POST 创建会话，新会话会替换旧会话。

/v1/assets/real-person/callback/... 是 Ark H5 自动跳转的回调地址，调用方不应自行请求或拼接该地址。

4. 查询认证结果 ​

客户端可轮询认证状态，例如每 5 秒查询一次：

bash
curl https://llm.xiaoyue9527.xyz/v1/assets/groups/astgrp_REPLACE_ME/verification-sessions/vrps_REPLACE_ME \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME'

认证会话状态如下：

status说明
pending等待本人完成认证，或 Ark 结果仍在同步
succeeded认证成功，真人素材组已激活
failed本次认证未完成或结果校验失败，可重新发起
expired认证链接已过期，可重新发起
revoked认证授权已撤销，不可继续使用

认证成功时响应包含 verified_at，对应素材组状态变为 active。随后查询 GET /v1/assets/groups，应看到该组的 verification_basis 为 h5_liveness 且 usable_for_current_key=true。

5. 通过 HTTPS 地址添加本人素材 ​

仅可向已激活、且属于当前租户的真人素材组添加该本人素材：

bash
curl -X POST https://llm.xiaoyue9527.xyz/v1/assets \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "本人正面视频",
    "asset_type": "real_person",
    "group_id": "astgrp_REPLACE_ME",
    "media_type": "video",
    "source": {
      "type": "url",
      "url": "https://cdn.example.com/video-assets/real-person.mp4"
    },
    "rights_attestation": {
      "accepted": true,
      "terms_version": "video-asset-rights-v1"
    }
  }'

6. 从本地文件添加本人素材 ​

当 managed_file_source_enabled=true 时，可先把本地文件直传到平台托管存储。必须从 managed_file_rules 中选择与目标 asset_type 和 media_type 完全匹配的一条规则，并原样使用其 module、purpose、max_size_bytes 与 mime_types，不要硬编码环境中的当前限制。

下面以真人 MP4 视频为例。先创建上传会话：

bash
curl -X POST https://llm.xiaoyue9527.xyz/v1/files/uploads \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{
    "module": "video",
    "purpose": "ark_real_video",
    "filename": "real-person.mp4",
    "content_type": "video/mp4",
    "size_bytes": 10485760
  }'

成功返回 201，其中包含 file_id、upload_id 和一次性 upload：

json
{
  "file_id": "fil_REPLACE_ME",
  "upload_id": "upl_REPLACE_ME",
  "status": "pending",
  "upload": {
    "method": "PUT",
    "url": "https://storage.example.com/signed-upload",
    "expires_at": 1786602600,
    "required_headers": {
      "Content-Type": "video/mp4",
      "X-Tos-Forbid-Overwrite": "true"
    }
  }
}

按响应中的 upload.method 向 upload.url 直传原始文件，并精确携带 upload.required_headers。这是对象存储签名地址，不得携带网关的 Authorization、JWT 或 Cookie。上传成功后通知平台校验：

bash
curl -X POST https://llm.xiaoyue9527.xyz/v1/files/uploads/upl_REPLACE_ME/complete \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -d '{}'

当前实现校验成功时响应为 status=ready；也可用 GET /v1/files/{file_id} 查询状态。若兼容环境返回 pending 或 verifying，则继续轮询；仅在 status=ready 后创建素材。创建素材时把 HTTPS source 替换为：

json
"source": {
  "type": "file",
  "file_id": "fil_REPLACE_ME"
}

上传地址和短期下载地址都属于敏感临时凭据，不应写入日志或持久化。如需创建短期下载地址，可调用 POST /v1/files/{file_id}/download-url；expires_in_seconds 允许 60 至 900 秒，省略时为 300 秒。文件已被素材引用时不能直接删除；删除素材后再按需调用 DELETE /v1/files/{file_id}。

7. 同步素材状态 ​

真人素材先返回 processing。可重复调用 POST /v1/assets/{asset_id}/sync 同步 Ark 处理状态，直到素材变为 active 或失败；只有 active 素材才能参与视频生成。删除真人素材组会撤销该组认证授权；删除素材组前必须先删除组内全部素材。

在视频任务中使用 ​

把返回的 uri 放入视频任务的媒体字段：

json
{
  "model": "seedance-2-0",
  "content": [
    {
      "type": "text",
      "text": "镜头缓慢推进，保持产品主体一致"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "llmgw_asset://ast_123"
      },
      "role": "reference_image"
    }
  ],
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p"
}

平台会校验素材归属、状态、有效期和媒体类型，并把素材版本写入视频任务快照。删除素材不会改写已创建任务的历史快照。

错误 ​

HTTPerror.code说明
400invalid_asset_urlURL 不符合 HTTPS 或安全要求
400asset_rights_required未确认素材使用权
400invalid_asset_terms_version素材组或素材使用了错误的授权条款版本
400unsupported_asset_group_type素材组类型不支持当前操作
400asset_group_required虚拟人或真人素材缺少 group_id
400unsupported_asset_sourcesource.type 或 url/file_id 组合无效
400asset_model_incompatible素材类型不受当前模型支持
400invalid_file_request文件上传或下载请求参数无效
404asset_not_found素材不存在或不属于当前租户
404asset_group_not_found素材组不存在或不属于当前租户
404verification_session_not_found真人认证会话不存在或不属于当前租户
404file_not_found / upload_not_found文件或上传会话不存在
403asset_provider_permission_deniedArk 素材控制面权限不足
403real_person_agreement_not_authorized当前 API Key 未获企业协议真人组授权
403agreement_group_admin_managed企业协议素材组只能由平台管理员管理
403file_purpose_forbidden当前文件用途不允许从公开接口上传
409real_person_verification_not_ready当前环境尚未启用真人认证能力
409real_person_agreement_group_admin_import_required企业协议真人组必须由平台管理员导入
409real_person_already_verified真人素材组已经完成认证
409asset_group_not_pending当前真人素材组状态不能发起认证
409asset_group_not_empty素材组仍有素材，不能删除
409asset_verification_not_valid真人认证或协议授权已失效
409asset_not_active素材已停用、删除或过期
409asset_provider_binding_not_ready供应商私域素材绑定尚未就绪
409asset_provider_subscription_required当前 Ark 账号创建能力需要额外权益
409asset_group_not_active素材组尚未激活
409asset_source_file_not_ready / asset_source_file_purpose_invalid文件尚未就绪或用途与素材不匹配
409file_not_ready / file_in_use / file_state_conflict文件当前状态不允许操作
410upload_expired上传会话已过期，应重新创建
413file_too_large文件超过能力规则给出的大小限制
415file_type_not_allowed / asset_source_file_type_not_allowed文件类型或实际媒体信息不符合能力规则
422file_verification_failed文件内容校验失败
500verification_session_poll_failed真人认证结果同步暂时失败
502asset_provider_request_failedArk 素材控制面请求失败
503verification_provider_rate_limited / verification_launch_link_failedArk 真人认证服务限流或链接创建暂时失败
503managed_files_disabled / video_file_sources_disabled / file_storage_unavailable / asset_source_file_unavailable托管文件能力未启用或暂时不可用

对认证或文件链路的 5xx 错误应使用指数退避重试，避免盲目重复创建会话或文件。火山方舟官方私域素材使用平台托管的控制面 AK/SK；未配置或 binding 未就绪时不会静默降级到普通 URL。

OpenAI-compatible API documentation.

LLMGateway