素材库
上传一次、由平台长期保存,之后在视频请求里用 `asset://ast_…` 引用。
工作方式#
素材库保存你的参考图片、视频与音频。上传后得到一个素材 ID(ast_…)与引用地址(asset://ast_…),把引用地址填进视频请求的参考素材位置即可,不必每次重新上传,也不必自己准备公网地址。素材一直保存到你删除为止。
- 1
上传
POST /v1/library/assets,multipart 上传文件,或给一个公网 URL 由平台拉取。 - 2
等待就绪
新素材处于
processing,平台校验格式与尺寸并生成预览,通常几秒内变为ready。 - 3
为模型准备与审核
POST .../assets/{id}/prepare指定模型,再轮询GET .../assets/{id}/readiness?model=...;需要审核的模型须取得approved。 - 4
引用
在
/v1/videos的input_reference或方舟协议content[]的 url 里写asset://ast_…。 - 5
管理
列表、改名、分组、删除;也可以在控制台的 素材库 页面可视化管理。
asset_not_found。支持的格式与上限#
格式按文件内容判断,与扩展名和 Content-Type 无关。这是入库时的通用上限;具体模型对引用数量、总时长、分辨率可能有更严的要求,以模型说明为准。
上传素材#
POST /v1/library/assets。支持三种写法:multipart 文件上传(推荐,大视频请用这种)、JSON 给 url 由平台拉取、JSON 给 data(base64 或 data URI,原件不超过 10 MB)。
filefile- multipart 文件字段。与
url/data三选一。 urlstring- JSON 方式:公网 http(s) 地址,平台去拉取。内网与本机地址会被拒绝。
datastring- JSON 方式:base64 或
data:image/png;base64,…。 namestring- 展示名,缺省取文件名。
group_idstring- 放入某个素材组(
grp_…),缺省为未分组。
multipart 上传
curl https://cmitoken.xmu.edu.my/v1/library/assets \ -H "Authorization: Bearer $OGROUTER_API_KEY" \ -F file=@./hero.png \ -F name=主角-正面 \ -F group_id=grp_7312894470000000从公网地址导入
curl https://cmitoken.xmu.edu.my/v1/library/assets \ -H "Authorization: Bearer $OGROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/hero.png", "name": "主角-正面" }'响应(201)
{ "id": "ast_7312894471029760", "object": "asset", "uri": "asset://ast_7312894471029760", "kind": "image", "purpose": "general", "name": "主角-正面", "group_id": "grp_7312894470000000", "project_id": null, "status": "processing", "media_type": "image/png", "size_bytes": 2310455, "preview_url": "https://cmitoken.xmu.edu.my/v1/assets/library/u/.../original.png?exp=...&sig=...", "use_count": 0, "deduplicated": false, "created_at": "2026-09-29T08:00:00Z", "updated_at": "2026-09-29T08:00:00Z"}deduplicated: true),不新占存储。等待处理完成#
GET /v1/library/assets/{id}?wait=10 会最多等待 10 秒直到素材离开 processing,比短间隔轮询更省请求。
等待就绪
curl "https://cmitoken.xmu.edu.my/v1/library/assets/ast_7312894471029760?wait=10" \ -H "Authorization: Bearer $OGROUTER_API_KEY"常见的 reject_code:dimension_out_of_range(宽高超范围)、aspect_ratio_out_of_range(宽高比超范围)、duration_out_of_range(时长超范围)、fps_out_of_range(帧率超范围)、probe_failed(文件损坏或无法解码)。被拒的素材不占用存储额度。
为目标模型准备与审核#
本地 ready 只表示文件处理完成。真人素材需要为实际生成模型单独提交准备,并主动查询审核结果;上传或登记成功不能替代审核通过。新增接口在部署并开通对应模型后可用,缺少兼容能力或审核配置时返回 unsupported。
提交准备:已就绪 200,异步处理中 202
curl -i https://cmitoken.xmu.edu.my/v1/library/assets/ast_7312894471029760/prepare \ -H "Authorization: Bearer $OGROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"doubao-seedance-2-0-fast-260128"}'查询准备与审核结果(200)
curl -i "https://cmitoken.xmu.edu.my/v1/library/assets/ast_7312894471029760/readiness?model=doubao-seedance-2-0-fast-260128" \ -H "Authorization: Bearer $OGROUTER_API_KEY"model 必填,须与随后的视频请求一致且在 Key 的权限内。后台主动查询审核状态,客户端按 Retry-After 查询本站 readiness,未给间隔时建议每 3 秒查询。准备接口不会创建视频任务或预扣视频生成费用。重复准备复用记录,换模型需重新查询。
review_status:not_submitted 尚未提交审核或该模型无需审核;pending 等待结果;approved 已通过查询确认;failed 未通过;unknown 结果未明,不得按通过处理。必须单独查询返回 Active 后才映射为 approved,上传返回素材 ID 不能代替审核结果。协议没有列出完整原始状态枚举,程序应使用本站 status 与 review_status,不从其它原始值猜测通过。
已查询确认审核通过的结果
{ "asset_id": "ast_7312894471029760", "model": "doubao-seedance-2-0-fast-260128", "status": "ready", "review_status": "approved", "upstream_status": "Active", "retryable": false, "updated_at": "2026-10-19T08:00:06Z"}asset://ast_... 引用;直接公网 URL 或内联参考返回 asset_reference_unsupported。纯文本生成不受影响,其它已支持 URL 参考的模型保持各自能力。ready + not_submitted 只表示该模型无需素材审核,不是取得了真人审核结论。审核通过也不替代客户取得合法肖像使用授权。在视频请求中引用#
OpenAI 协议把引用地址写进 input_reference(也接受 {"asset_id": "ast_…"});方舟协议写进 image_url / video_url / audio_url 的 url。提示词里可用“图片1、视频1”按出现顺序指代参考素材。
OpenAI 协议
curl https://cmitoken.xmu.edu.my/v1/videos \ -H "Authorization: Bearer $OGROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedance-2-0-260128", "prompt": "图片1中的人物缓缓转身,镜头推近", "seconds": 5, "resolution": "720p", "input_reference": "asset://ast_7312894471029760" }'方舟协议:图片 + 参考视频
curl https://cmitoken.xmu.edu.my/api/v3/contents/generations/tasks \ -H "Authorization: Bearer $OGROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedance-2-0-260128", "content": [ { "type": "text", "text": "图片1中的人物按视频1的运镜走进画面" }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://ast_7312894471029760" } }, { "type": "video_url", "role": "reference_video", "video_url": { "url": "asset://ast_7312894471029999" } } ], "resolution": "720p", "duration": 5 }'asset_preparing、asset_review_failed、asset_reference_unsupported 不创建视频任务,不预扣视频生成费用。平台按所选模型的素材协议转换引用;客户始终使用本站 URI。Python:上传、本地处理、模型审核、生成
import os, time, requests
API = "https://cmitoken.xmu.edu.my/v1"MODEL = "doubao-seedance-2-0-fast-260128"HEADERS = {"Authorization": f"Bearer {os.environ['OGROUTER_API_KEY']}"}
def checked(response): response.raise_for_status() return response.json()
# 1. Upload and wait for local processing.with open("portrait.png", "rb") as source: asset = checked(requests.post(API + "/library/assets", headers=HEADERS, files={"file": source}, timeout=120))asset_path = API + "/library/assets/" + asset["id"]deadline = time.monotonic() + 300while asset["status"] == "processing": if time.monotonic() >= deadline: raise TimeoutError("Local asset processing timed out") asset = checked(requests.get(asset_path, params={"wait": 10}, headers=HEADERS, timeout=30))if asset["status"] != "ready": raise RuntimeError(asset.get("reject_reason", "Local validation failed"))
# 2. Prepare for this model. Upload success is not review approval.response = requests.post(asset_path + "/prepare", headers=HEADERS, json={"model": MODEL}, timeout=60)state = checked(response)deadline = time.monotonic() + 300while state["status"] == "preparing": if time.monotonic() >= deadline: raise TimeoutError("Asset review timed out; resume with GET readiness") delay = max(1, min(30, int(response.headers.get("Retry-After", "3")))) time.sleep(delay) response = requests.get(asset_path + "/readiness", params={"model": MODEL}, headers=HEADERS, timeout=30) state = checked(response)if state["status"] != "ready" or state["review_status"] not in ("approved", "not_submitted"): raise RuntimeError(state.get("reason", "Asset is not ready for this model"))
# 3. Submit using the same model and the site's asset URI.# Keep this key when retrying this business operation.task = checked(requests.post(API + "/videos", headers={**HEADERS, "Idempotency-Key": "portrait-video-20261019-001"}, json={ "model": MODEL, "prompt": "A slow, natural turn of the person in image 1", "seconds": 5, "input_reference": asset["uri"],}, timeout=60))print(task["id"])管理素材与分组#
分页列表
# 第一页curl "https://cmitoken.xmu.edu.my/v1/library/assets?kind=image&limit=30" \ -H "Authorization: Bearer $OGROUTER_API_KEY"
# 下一页:把上一页的 next_cursor 原样传回curl "https://cmitoken.xmu.edu.my/v1/library/assets?kind=image&limit=30&cursor=ast_7312894471029000" \ -H "Authorization: Bearer $OGROUTER_API_KEY"改名、移出分组、删除
curl -X PATCH https://cmitoken.xmu.edu.my/v1/library/assets/ast_7312894471029760 \ -H "Authorization: Bearer $OGROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "主角-定稿", "group_id": null }'
curl -X DELETE https://cmitoken.xmu.edu.my/v1/library/assets/ast_7312894471029760 \ -H "Authorization: Bearer $OGROUTER_API_KEY"响应里的 preview_url、thumb_url、poster_url 是 1 小时有效的签名地址,适合直接放进 <img> / <video>,不要长期保存;需要时重新请求详情即可。
存储额度#
每个账号有免费存储额度与硬上限,按用户等级给出,以 GET /v1/library/usage 的返回为准。处理中与可用的素材计入用量,删除或被拒即归还。
查询用量
curl https://cmitoken.xmu.edu.my/v1/library/usage \ -H "Authorization: Bearer $OGROUTER_API_KEY"
# {"used_bytes": 734003200, "asset_count": 58, "free_bytes": 1073741824,# "hard_cap_bytes": 53687091200, "overage_billing": false}storage_payment_required,超过硬上限时返回 403 storage_quota_exceeded。目前超出免费额度后暂不能继续上传(overage_billing 为 false),按量计费开放后会在此说明。错误码#
错误响应的整体结构与重试建议见 错误码。