素材

把可复用的参考图 / 视频 / 音频注册成素材，之后在视频任务里用 asset:// 引用。

什么时候需要素材#

多数视频任务的参考素材直接在请求里填公网 URL 即可。部分服务还支持把素材注册一次、跨任务用 asset:// 复用。用 GET /openapi/v2/services 看服务的 material_mode：auto_create 表示直接传公网 URL；direct_or_user_created 表示也可以创建素材，等它变为 active 后再引用。

不计费

注册素材本身不花钱。计费发生在引用它的那条视频任务上，而不是素材本身。素材归属于你的账号，不能跨用户或跨服务引用。

注册素材#

两种注册方式。无论哪种，注册都是异步的：响应为 processing，轮询到 active 即可使用。Idempotency-Key 必填——同一把键重试会返回原素材，而不是注册（或重复上传）第二份。

A. 公网地址（JSON）

bash

curl https://jxsyn.com/v1/openapi/v2/materials \  -H "X-API-Key: $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: material-20260920-0001" \  -d '{    "service_code": "seedance2-0-20260828",    "asset_type": "Image",    "source_url": "https://cdn.example.com/reference.jpg",    "name": "商品参考图"  }'

B. 本地文件（multipart）——图片 ≤ 32 MiB，音视频 ≤ 200 MiB

bash

curl https://jxsyn.com/v1/openapi/v2/materials \  -H "X-API-Key: $OGROUTER_API_KEY" \  -H "Idempotency-Key: material-20260920-0002" \  -F service_code=seedance2-0-20260828 \  -F asset_type=Image \  -F name="商品参考图" \  -F file=@./reference.jpg

service_code必填: 支持用户素材的公开服务编码。
asset_type必填: Image、Video 或 Audio（首字母大写）。上传文件时须与文件 MIME 大类一致。
source_url: 仅 JSON：公网 HTTP(S) 文件地址，不含凭证。
file: 仅 multipart：本地文件。平台会先托管它，再把签名地址交给上游。
name: 便于自己管理的名称（选填）。

状态与轮询#

状态	含义	客户端处理
processing	上游正在拉取与校验	轮询 GET /openapi/v2/materials/{id} 或 POST .../refresh
active	已就绪	在任务里用 asset:// 引用
failed	处理失败	读取 error_code / error_message

超过死线（约两小时）仍未就绪会判为 failed。

列出、查询与刷新#

除创建外还有三个读接口，都用同一把 API Key，且只会返回你自己的素材。

方法	路径	作用
GET	/openapi/v2/materials/services	列出接受用户素材的服务（service_code 从这里取）
GET	/openapi/v2/materials	分页列出你的素材
GET	/openapi/v2/materials/{id}	查询单条素材
POST	/openapi/v2/materials/{id}/refresh	主动同步上游状态（无请求体）

列表（page / page_size）

bash

curl "https://jxsyn.com/v1/openapi/v2/materials?page=1&page_size=20" \  -H "X-API-Key: $OGROUTER_API_KEY"

查询单条

bash

curl https://jxsyn.com/v1/openapi/v2/materials/asset-1949000000000000041 \  -H "X-API-Key: $OGROUTER_API_KEY"

刷新状态

bash

curl -X POST https://jxsyn.com/v1/openapi/v2/materials/asset-1949000000000000041/refresh \  -H "X-API-Key: $OGROUTER_API_KEY"

列表响应是 { page, page_size, offset, total, materials }，每项与创建响应相同；查询与刷新返回 { material }。

在任务里引用#

变为 active 后，把 asset_ref 填在原本放媒体 URL 的位置。只有你自己的 active 素材能解析；auto_create 模式的服务会拒绝 asset://。

json

{  "type": "image_url",  "role": "reference_image",  "image_url": { "url": "asset://asset-1949000000000000041" }}

可以在控制台的素材库里管理，也可以完全走 API。错误处理与请求 ID 与其它端点一致，见错误处理。

改名、删除与筛选#

用 PATCH 改素材名或把它移入/移出某个素材组；用 DELETE 删除自己的素材。删除后它的 asset:// 引用立即失效。

改名 / 移入组

bash

curl -X PATCH https://jxsyn.com/v1/openapi/v2/materials/asset-1949000000000000041 \  -H "X-API-Key: $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "新名字", "group_id": "group-1949000000000000099" }'

删除

bash

curl -X DELETE https://jxsyn.com/v1/openapi/v2/materials/asset-1949000000000000041 \  -H "X-API-Key: $OGROUTER_API_KEY"

列表接口支持筛选：?status=active&asset_type=Image&q=关键字&group_id=group-xxx（group_id=none 只看未分组素材）。

素材组（锁人脸 / 角色一致性）#

素材组把同一主体（一个人、一个角色、一个产品）的多张参考绑在一起。任务里用 asset://group-<id> 整组引用，用于稳定跨镜头的人脸 / 角色一致性。组绑定单一服务，组内素材必须同服务。引用一个组会把组内 active 成员作为参考图带入，因此总张数仍受该模型的参考图数量上限约束。

新建组

bash

curl https://jxsyn.com/v1/openapi/v2/material-groups \  -H "X-API-Key: $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "service_code": "seedance2-0-20260828",    "name": "主角小明",    "subject_type": "face"  }'

subject_type 取 face / character / product / style / other。把素材放进组：建素材时带 group_id，或把已有素材移入。

把已有素材加入组

bash

curl https://jxsyn.com/v1/openapi/v2/material-groups/group-1949000000000000099/materials \  -H "X-API-Key: $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "material_ids": ["asset-...", "asset-..."] }'

方法	路径	用途
GET	/openapi/v2/material-groups	列出我的组
GET	/openapi/v2/material-groups/{id}	组详情（含成员）
PATCH	/openapi/v2/material-groups/{id}	改名 / 主体类型 / 封面
DELETE	/openapi/v2/material-groups/{id}	删组（带 ?delete_members=true 连成员一并删）
DELETE	/openapi/v2/material-groups/{id}/materials/{mid}	移出单个成员（素材保留）

在任务里整组引用

json

{  "type": "image_url",  "role": "reference_image",  "image_url": { "url": "asset://group-1949000000000000099" }}

配额

每账户：素材最多 500 张、素材组最多 50 个、单组成员最多 20 张。组内至少要有一个 active 成员才能被引用。

素材

把可复用的参考图 / 视频 / 音频注册成素材，之后在视频任务里用 asset:// 引用。

什么时候需要素材#

不计费

注册素材本身不花钱。计费发生在引用它的那条视频任务上，而不是素材本身。素材归属于你的账号，不能跨用户或跨服务引用。

注册素材#

A. 公网地址（JSON）

bash

curl https://jxsyn.com/v1/openapi/v2/materials \  -H "X-API-Key: $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: material-20260920-0001" \  -d '{    "service_code": "seedance2-0-20260828",    "asset_type": "Image",    "source_url": "https://cdn.example.com/reference.jpg",    "name": "商品参考图"  }'

B. 本地文件（multipart）——图片 ≤ 32 MiB，音视频 ≤ 200 MiB

bash

curl https://jxsyn.com/v1/openapi/v2/materials \  -H "X-API-Key: $OGROUTER_API_KEY" \  -H "Idempotency-Key: material-20260920-0002" \  -F service_code=seedance2-0-20260828 \  -F asset_type=Image \  -F name="商品参考图" \  -F file=@./reference.jpg

service_code必填: 支持用户素材的公开服务编码。
asset_type必填: Image、Video 或 Audio（首字母大写）。上传文件时须与文件 MIME 大类一致。
source_url: 仅 JSON：公网 HTTP(S) 文件地址，不含凭证。
file: 仅 multipart：本地文件。平台会先托管它，再把签名地址交给上游。
name: 便于自己管理的名称（选填）。

状态与轮询#

状态	含义	客户端处理
processing	上游正在拉取与校验	轮询 GET /openapi/v2/materials/{id} 或 POST .../refresh
active	已就绪	在任务里用 asset:// 引用
failed	处理失败	读取 error_code / error_message

超过死线（约两小时）仍未就绪会判为 failed。

列出、查询与刷新#

除创建外还有三个读接口，都用同一把 API Key，且只会返回你自己的素材。

方法	路径	作用
GET	/openapi/v2/materials/services	列出接受用户素材的服务（service_code 从这里取）
GET	/openapi/v2/materials	分页列出你的素材
GET	/openapi/v2/materials/{id}	查询单条素材
POST	/openapi/v2/materials/{id}/refresh	主动同步上游状态（无请求体）

列表（page / page_size）

bash

curl "https://jxsyn.com/v1/openapi/v2/materials?page=1&page_size=20" \  -H "X-API-Key: $OGROUTER_API_KEY"

查询单条

bash

curl https://jxsyn.com/v1/openapi/v2/materials/asset-1949000000000000041 \  -H "X-API-Key: $OGROUTER_API_KEY"

刷新状态

bash

curl -X POST https://jxsyn.com/v1/openapi/v2/materials/asset-1949000000000000041/refresh \  -H "X-API-Key: $OGROUTER_API_KEY"

列表响应是 { page, page_size, offset, total, materials }，每项与创建响应相同；查询与刷新返回 { material }。

在任务里引用#

变为 active 后，把 asset_ref 填在原本放媒体 URL 的位置。只有你自己的 active 素材能解析；auto_create 模式的服务会拒绝 asset://。

json

{  "type": "image_url",  "role": "reference_image",  "image_url": { "url": "asset://asset-1949000000000000041" }}

可以在控制台的素材库里管理，也可以完全走 API。错误处理与请求 ID 与其它端点一致，见错误处理。

改名、删除与筛选#

用 PATCH 改素材名或把它移入/移出某个素材组；用 DELETE 删除自己的素材。删除后它的 asset:// 引用立即失效。

改名 / 移入组

bash

curl -X PATCH https://jxsyn.com/v1/openapi/v2/materials/asset-1949000000000000041 \  -H "X-API-Key: $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "新名字", "group_id": "group-1949000000000000099" }'

删除

bash

curl -X DELETE https://jxsyn.com/v1/openapi/v2/materials/asset-1949000000000000041 \  -H "X-API-Key: $OGROUTER_API_KEY"

列表接口支持筛选：?status=active&asset_type=Image&q=关键字&group_id=group-xxx（group_id=none 只看未分组素材）。

素材组（锁人脸 / 角色一致性）#

新建组

bash

curl https://jxsyn.com/v1/openapi/v2/material-groups \  -H "X-API-Key: $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "service_code": "seedance2-0-20260828",    "name": "主角小明",    "subject_type": "face"  }'

subject_type 取 face / character / product / style / other。把素材放进组：建素材时带 group_id，或把已有素材移入。

把已有素材加入组

bash

curl https://jxsyn.com/v1/openapi/v2/material-groups/group-1949000000000000099/materials \  -H "X-API-Key: $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "material_ids": ["asset-...", "asset-..."] }'

方法	路径	用途
GET	/openapi/v2/material-groups	列出我的组
GET	/openapi/v2/material-groups/{id}	组详情（含成员）
PATCH	/openapi/v2/material-groups/{id}	改名 / 主体类型 / 封面
DELETE	/openapi/v2/material-groups/{id}	删组（带 ?delete_members=true 连成员一并删）
DELETE	/openapi/v2/material-groups/{id}/materials/{mid}	移出单个成员（素材保留）

在任务里整组引用

json

{  "type": "image_url",  "role": "reference_image",  "image_url": { "url": "asset://group-1949000000000000099" }}

配额

每账户：素材最多 500 张、素材组最多 50 个、单组成员最多 20 张。组内至少要有一个 active 成员才能被引用。