即梦 Agent 接口文档
更新日期:2026-11-04
面向通过平台账号和 API 令牌接入的开发者。首次调用见创建任务,复用素材见素材管理,费用见计费与试用。左侧目录可随时跳转章节。
1. 接入指南
1.1 接入约定
| 配置项 | 说明 |
|---|---|
BASE_URL |
https://token.metaset.top(本平台服务地址,末尾不加 /) |
CHANNEL_API_TOKEN |
渠道自己账号下创建的 API 令牌 |
| 鉴权 | Authorization: Bearer <CHANNEL_API_TOKEN> |
| 创建请求格式 | Content-Type: application/json,UTF-8 编码 |
| 任务标识 | 创建响应中的 data.task_id,按字符串保存 |
调用前,确认账号已开通所选模型、令牌有权使用,且余额或试用次数充足。
调用流程:提交创建请求 → 保存 task_id → 定期查询任务 → 成功后读取视频地址并下载保存。
1.2 服务能力
四个模型共用创建和查询接口:顶层 model 选择模型,input 填写创作参数。
1.2.1 怎么选短片创作模型
从已开通的模型中按时长、分辨率选择。首次联调可用第 2.1 节的 Mini 示例;需要视频编辑或延长时选 Seedance 2.5。
model(完整填写) |
时长(秒) | 分辨率 |
|---|---|---|
jimeng-agent-seedance20-mini |
5–15 | 480P、720P |
jimeng-agent-seedance20-fast |
5–15 | 480P、720P |
jimeng-agent-seedance20 |
5–15 | 480P、720P、1080P、4K |
jimeng-agent-seedance25 |
5–30 | 480P、720P、1080P |
表中时长为普通生成的整数秒范围;默认时长 15 秒、分辨率 720P。4K 与超过 15 秒的组合暂无模型支持;编辑时长规则见视频编辑与延长。
Mini 与 Fast 的参数相同,但速度、画质和费用需结合相同输入的实际结果比较,本文不承诺优劣或价格排序。
请显式填写表中的完整 model。旧请求省略模型时默认使用 jimeng-agent-seedance20-fast,不会自动匹配已开通模型,可能因权限或无可用渠道而失败。短片模型当前向即梦提交时使用能力标识 direct_model;旧能力标识 pippit_video_part_agent 在过渡期仍可作为请求兼容值传入,但新请求建议使用 direct_model。
1.2.2 通用能力
| 能力 | 当前支持范围 |
|---|---|
| 创作方式 | 文字描述,可附加图片、视频或音频参考素材;generate_type 可选择参考生成或首尾帧生成 |
| 视频编辑 / 延长 | 仅 jimeng-agent-seedance25 支持,分别使用 task_type=edit / extend |
| 声音 / 尾帧 | 可请求无声视频或输出视频的尾帧图片,见创建参数表 |
2. 任务接口
2.1 创建短片创作任务
POST {BASE_URL}/jimeng-agent/v1/tasks
Authorization: Bearer <CHANNEL_API_TOKEN>
Content-Type: application/json
最小请求示例(需开通 Mini):
{
"model": "jimeng-agent-seedance20-mini",
"input": {
"prompt": "海边日出,镜头缓慢推进",
"duration": 15,
"resolution": "480P",
"ratio": "16:9"
}
}
创建成功示例:
{
"code": "0",
"data": {
"action_key": "generate_video",
"capability_key": "direct_model",
"status": "CREATED",
"task_id": "task_xxxxxxxxx",
"Jimeng_id": "7701186827004663065",
"usage": {
"withhold_token": 643500
}
}
}
code="0" 表示已受理,视频尚未生成。保存实际返回的 data.task_id 用于查询;所有任务类型均使用此 ID,不自行传 run_id。创建与查询共用响应字段,示例用量不是固定值。
2.1.1 参数说明
| 字段 | 类型 | 必填 / 默认值 | 说明 |
|---|---|---|---|
model |
string | 建议显式填写 | 已开通的完整模型名,范围及省略行为见第 1.2.1 节 |
input |
object | 必填 | 短片创作参数对象,不能传 JSON 字符串或数组 |
input.prompt |
string | 必填 | 创作提示词,不能全为空白;素材地址放在对应 URL 数组,不能仅写入提示词 |
input.duration |
integer | 普通生成 / 延长默认 15;编辑默认 -1 |
输出时长(秒),范围见模型表。Seedance 2.5 的编辑标记与省略规则见第 2.1.4 节 |
input.resolution |
string | 默认 720P |
输出分辨率,按模型表中的大写值填写 |
input.ratio |
string | 可选 | 输出宽高比:21:9、16:9、4:3、1:1、3:4、9:16、adaptive。编辑 / 延长仅支持 adaptive,省略时自动补齐 |
input.seed |
integer | 可选 | 随机种子,32 位有符号整数,范围 -2147483648 至 2147483647,0 是有效值 |
input.enable_watermark |
boolean | 默认 false |
是否启用水印 |
input.task_type |
string | 可选 | 仅 Seedance 2.5 支持:edit 编辑、extend 延长;普通生成时省略。兼容规则见第 2.1.4 节 |
input.output_format |
string | 默认 mp4 |
输出封装格式:mp4 或 mov;mov 仅 Seedance 2.5 支持 |
input.draft |
boolean | 可选 | 仅 Seedance 2.5 支持;true 生成样片,固定 480P,不能与 draft_task_id 同时传入 |
input.draft_task_id |
string | 可选 | 仅 Seedance 2.5 支持;填写已成功样片的即梦十进制任务 ID,将样片转成成片。传入后 input 只能包含此字段,样片参数由平台沿用 |
input.aigc_meta |
object | 可选 | 成片 AIGC 元数据;使用时必须同时填写 content_producer、producer_id、content_propagator、propagate_id,每项为 1–1024 位字母、数字、下划线或连字符 |
input.generate_type |
string | 默认 reference |
生成类型:reference 表示参考生视频,first_last_frame 表示首尾帧生视频;素材仍填写到对应 URL 数组中 |
input.generate_audio |
boolean | 即梦默认 true |
是否生成声音;false 请求无声视频,四个模型均支持 |
input.return_last_frame |
boolean | 即梦默认 false |
是否返回输出视频尾帧;true 时从查询结果的 data.video_artifact.last_frame_url 获取,四个模型均支持 |
input.image_url_list |
string[] | 可选 | 参考图片 HTTP(S) URL 或 asset://<Id> 数组;Seedance 2.0 系列最多 9 张,Seedance 2.5 最多 30 张 |
input.video_url_list |
string[] | 可选 | 参考视频 HTTP(S) URL 或 asset://<Id> 数组;Seedance 2.0 系列最多 3 条,Seedance 2.5 最多 10 条 |
input.audio_url_list |
string[] | 可选 | 参考音频 HTTP(S) URL 或 asset://<Id> 数组;Seedance 2.0 系列最多 3 条,Seedance 2.5 最多 10 条 |
字段格式: 默认值仅在省略时生效;null、空字符串不等同于省略。整数使用 JSON 数字,布尔值使用 true / false,不接受字符串或数字替代布尔值。URL 列表始终为数组,无素材时省略或传 [];媒体规格见下一节,素材引用见第 3.6 节。
声音与尾帧开关自插件 1.3.2 起支持,省略时沿用即梦默认值,显式 false 会保留。须在首次创建时指定,不能通过重复提交或查询补改。输出尾帧与 generate_type=first_last_frame 的输入首尾帧是两个功能。
2.1.2 参考素材要求
素材使用公网可直接下载的 HTTP(S) 文件直链,或当前用户的 asset://<Id> 引用。不支持本地/内网地址、localhost、Base64,以及需要登录、Cookie 或额外请求头的链接。临时签名应在任务处理期间有效。
2.1.2.1 参考图片
Seedance 2.0 系列最多 9 张,Seedance 2.5 最多 30 张;每张图片须同时满足以下要求:
| 检查项 | Seedance 2.0 系列(jimeng-agent-seedance20 / jimeng-agent-seedance20-fast / jimeng-agent-seedance20-mini) |
Seedance 2.5(jimeng-agent-seedance25) |
|---|---|---|
| 格式 | JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF | JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF |
| 宽高比(宽 ÷ 高) | 0.4 < 宽/高 < 2.5,不包含两个边界值 |
0.4 ≤ 宽/高 ≤ 2.5,包含两个边界值 |
| 宽、高分别满足 | 300 < 边长 < 6000 像素 |
300 ≤ 边长 ≤ 6000 像素 |
| 单张文件大小 | < 30 MB | < 30 MB |
尺寸与宽高比必须同时满足。例如 300×600 符合 Seedance 2.5 的要求,但不符合 Seedance 2.0 系列的宽度要求。
2.1.2.2 参考视频与音频
| 参考素材参数 | Seedance 2.0 / Fast / Mini | Seedance 2.5 |
|---|---|---|
input.video_url_list |
最多 3 条;数组内全部视频总时长 ≤ 15 秒 | 最多 10 条;数组内全部视频总时长 ≤ 30 秒 |
input.audio_url_list |
最多 3 条;数组内全部音频总时长 ≤ 15 秒 | 最多 10 条;数组内全部音频总时长 ≤ 30 秒 |
时长按各数组内素材相加,不按单条计算。duration 不会截短参考素材;编辑任务也须遵守上述限制。
使用 asset://<Id> 引用素材时,三类素材合计最多解析 50 个引用;Seedance 2.5 的图片、视频、音频上限合计正好为 50 个。
任务受理后仍可能因素材规格、下载失败或内容审核而失败,需检查查询结果的 status、err_code、err_msg。
2.1.3 完整参数示例
无外部素材的完整示例(请求无声视频及输出尾帧):
{
"model": "jimeng-agent-seedance20-mini",
"input": {
"prompt": "海边日出,镜头缓慢推进,写实电影质感",
"duration": 15,
"resolution": "480P",
"ratio": "16:9",
"seed": 0,
"enable_watermark": false,
"generate_type": "reference",
"generate_audio": false,
"return_last_frame": true,
"image_url_list": [],
"video_url_list": [],
"audio_url_list": []
}
}
需要参考素材时,将对应空数组替换为 URL 或素材引用,例如 "video_url_list": ["https://example.com/reference.mp4"]。混合引用见第 3.6 节。本文示例 URL 和 ID 均为占位值,发送前须替换。
2.1.4 视频编辑与延长示例
仅 jimeng-agent-seedance25 支持。编辑和延长的 ratio 只能为 adaptive,省略时自动补齐,传其他值会报错。
task_type |
duration |
平台处理 |
|---|---|---|
edit |
-1 或省略 |
跟随原视频时长,不接受正数时长 |
extend |
5–30 或省略 |
目标时长,默认 15 秒 |
| 省略 | JSON 数字 -1 |
自动补 task_type=edit,与显式编辑相同 |
| 省略 | 省略 | 不向即梦补时长,由即梦判断任务类型;普通生成默认 15 秒,编辑跟随原视频 |
-1 仅为编辑标记,其他模型、延长模式、字符串 "-1" 或 null 均不支持。平台不分析提示词改写任务类型;正数时长会原样提交,若即梦识别为编辑,可能报 20020。已知为编辑时请显式传 edit。
视频编辑示例:
{
"model": "jimeng-agent-seedance25",
"input": {
"prompt": "将视频中的白天场景改为夕阳时分,保留主体动作",
"task_type": "edit",
"duration": -1,
"ratio": "adaptive",
"resolution": "720P",
"generate_type": "reference",
"video_url_list": ["https://example.com/reference.mp4"]
}
}
视频延长示例:
{
"model": "jimeng-agent-seedance25",
"input": {
"prompt": "延续原视频的场景和运镜,让镜头继续向海面推进",
"task_type": "extend",
"duration": 15,
"ratio": "adaptive",
"resolution": "720P",
"video_url_list": ["https://example.com/reference.mp4"]
}
}
预扣费用见第 5.2 节,包含显式编辑、仅传 -1 和同时省略类型/时长的区别。
2.1.5 Seedance 2.5 封装格式与样片流程
jimeng-agent-seedance25 通过 input.output_format 支持 mp4 和 mov,省略时为 mp4。mov 是视频封装格式,浏览器直接下载时可能仍显示 .mp4 文件名,以下游返回的内容和平台链接为准。
样片与样片转成片是两个独立任务,也分别计费;实际消耗以创建或查询响应中的 data.usage 为准。
第一步生成样片。样片固定输出 480P,平台会自动补齐分辨率;如果显式传入其他分辨率会拒绝请求:
{
"model": "jimeng-agent-seedance25",
"input": {
"prompt": "黄昏的海边,一只海鸥掠过镜头",
"ratio": "16:9",
"draft": true
}
}
样片任务成功后,保存返回的 data.Jimeng_id(即梦样片任务 ID;如果直接调用即梦接口,则使用其 data.task_id),再提交样片转成片任务。此时 input 只能传 draft_task_id,不能重复传提示词、素材、时长、比例、种子、音频开关或其他样片参数;成片固定使用样片参数并输出 1080P:
{
"model": "jimeng-agent-seedance25",
"input": {
"draft_task_id": "上一步成功样片任务的 Jimeng_id"
}
}
MOV 成片示例:
{
"model": "jimeng-agent-seedance25",
"input": {
"prompt": "以参考图中的商品为主体,生成一条自然流畅的展示视频",
"duration": 5,
"ratio": "16:9",
"resolution": "1080P",
"output_format": "mov",
"image_url_list": ["https://example.com/reference.jpg"]
}
}
样片和成片任务都使用普通的预扣、成功结算和失败全额退款规则。样片任务的 Jimeng_id 仅用于后续 draft_task_id,不能跨账号或引用未成功的任务。
2.2 查询短片创作任务
GET {BASE_URL}/jimeng-agent/v1/tasks/{task_id}
Authorization: Bearer <CHANNEL_API_TOKEN>
| 参数 | 位置 | 类型 | 说明 |
|---|---|---|---|
task_id |
URL 路径 | string | 创建接口实际返回的 data.task_id |
无请求体(Postman Body 选 none),无需 model 或 run_id。使用任务所属账号的有效令牌,其他账号无法查询。
任务处理中示例:
{
"code": "0",
"data": {
"action_key": "generate_video",
"capability_key": "direct_model",
"status": "RUNNING",
"task_id": "task_xxxxxxxxx",
"Jimeng_id": "7701186827004663065"
}
}
任务成功示例(用量仅作示例,不是固定值):
{
"code": "0",
"data": {
"action_key": "generate_video",
"capability_key": "direct_model",
"status": "SUCCESS",
"task_id": "task_xxxxxxxxx",
"Jimeng_id": "7701186827004663065",
"usage": {
"actual_token": 643500,
"refund_token": 0,
"withhold_token": 643500
},
"video_artifact": {
"duration": 15,
"height": 496,
"temporary_original_video_url": "https://xxxx.doubao-seedance-x-x-fast/xxxxxxx",
"url": "https://example.com/result.mp4",
"width": 864
}
}
}
任务失败示例:
{
"code": "0",
"data": {
"action_key": "generate_video",
"capability_key": "direct_model",
"status": "FAILED",
"task_id": "task_xxxxxxxxx",
"Jimeng_id": "7701186827004663065",
"err_code": "20006",
"err_msg": "image width or height out of range",
"usage": {
"actual_token": 0,
"refund_token": 643500,
"withhold_token": 643500
}
}
}
外层 code="0" 不代表任务成功,必须检查 data.status。 失败示例为实际用量为零、预扣全退的情况;用量缺省的处理见响应字段说明。
2.2.1 状态及轮询
data.status |
含义 | 渠道处理方式 |
|---|---|---|
CREATED |
已创建 | 继续查询 |
QUEUED |
排队中 | 继续查询 |
RUNNING |
生成中 | 继续查询 |
SUCCESS |
已成功 | 停止轮询,读取视频地址 |
FAILED |
已失败 | 停止轮询,记录错误和任务 ID |
CANCELED |
已取消 | 停止轮询,按平台最终记录核对结算 |
UNKNOWN |
状态暂时无法确认 | 稍后查询;持续出现时联系平台支持 |
建议每 5–10 秒查询并逐步延长间隔,状态同步可能延迟;这不是完成时限。查询失败或前端等待超时后保留原 ID 稍后续查,避免重复创建。当前接口没有取消入口,CANCELED 仅为可能返回的状态。
2.2.2 完整响应字段
创建与查询共用以下字段。可选字段可能缺省,客户端应兼容新增字段;请求失败结构见第 4 节。时间和用量整数为非负安全整数(0–9007199254740991),视频尺寸与时长为正数。
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
code |
string | 始终返回 | 请求成功为 "0";不代表视频生成成功,仍需检查 data.status |
data |
object | 始终返回 | 当前任务信息 |
data.task_id |
string | 始终返回 | 对外任务 ID;后续查询使用此值,按字符串保存 |
data.Jimeng_id |
string | 已取得即梦任务 ID 时 | 即梦原响应的 data.task_id;字段名区分大小写,按字符串保存,勿转为数字;创建时即梦仅返回 run_id 则暂不返回此字段 |
data.status |
string | 始终返回 | 任务状态,取值和处理方式见第 2.2.1 节 |
data.capability_key |
string | 始终返回 | 能力标识;本文四个短片模型均为 direct_model |
data.action_key |
string | 始终返回 | 动作标识;短片生成固定为 generate_video |
data.start_at |
integer | 即梦返回有效值时 | 任务创建时间,Unix 秒数 |
data.elapsed_seconds |
integer | 即梦返回有效值时 | 耗时(秒),终态时为最终耗时 |
data.usage |
object | 有可用用量时返回 | 即梦返回的用量和估算信息对象;各子字段均可能独立缺省 |
data.usage.withhold_token |
integer | 即梦返回有效值时 | 预扣 Token 数 |
data.usage.actual_token |
integer | 即梦返回有效值时 | 实际消耗 Token 数,以完成后的值核对 |
data.usage.refund_token |
integer | 即梦返回有效值时 | 退回 Token 数 |
data.usage.check_token |
integer | 即梦返回有效值时 | 估算 Token 数,仅供诊断 |
data.usage.check_quota |
integer | 即梦返回有效值时 | 核验用量(秒)=最低参考视频时长+预计生成时长 |
data.usage.withhold_quota |
integer | 即梦返回有效值时 | 预扣业务用量(秒)=max(最低参考视频时长, 原始参考视频时长)+预计生成时长 |
data.usage.actual_quota |
integer | 即梦返回有效值时 | 实际业务用量(秒)=max(最低参考视频时长, 原始参考视频时长)+实际生成时长 |
data.video_artifact |
object | 成功且已有有效视频地址时 | 视频结果;任务未成功时不返回 |
data.video_artifact.url |
string | 有 video_artifact 时返回 |
视频播放或下载的 HTTP(S) 地址,可能带临时签名 |
data.video_artifact.temporary_original_video_url |
string | capability_key=direct_model 且即梦返回有效地址时 |
原始视频临时下载地址,仅保留 1 天;过期后即梦不会续期或重新生成。正式分发或长期存档请使用 url |
data.video_artifact.output_format |
string | 即梦返回有效封装格式时 | 输出封装格式:mp4 或 mov;缺省时按 mp4 处理 |
data.video_artifact.cover_url |
string | 有有效封面地址时 | 封面 HTTP(S) 地址,可缺省 |
data.video_artifact.last_frame_url |
string | 有有效尾帧地址时 | 输出尾帧 HTTP(S) 地址;创建时需设 input.return_last_frame=true,缺失不表示视频生成失败 |
data.video_artifact.duration |
number | 有有效时长时 | 实际时长(秒) |
data.video_artifact.width |
number | 有有效宽度时 | 实际宽度(像素) |
data.video_artifact.height |
number | 有有效高度时 | 实际高度(像素) |
data.err_code |
string | 失败或取消且有有效错误码时 | Jimeng 返回的任务错误码,例如 "20020";与外层请求状态 code 含义不同 |
data.err_msg |
string | 失败或取消时 | 优先返回即梦的原始错误说明,例如 image width or height out of range,不保证为中文;去除首尾空白、将控制字符替换为空格,最长 2048 字符。即梦未提供有效说明时,才按 err_code 返回中文说明;未知或缺失错误码时返回“任务执行失败”或“任务已取消” |
创建与查询使用相同的错误返回规则。即使创建响应已包含失败或取消状态,也会返回对应的 err_code(如有)和 err_msg。插件 1.3.7 起保留即梦的具体错误原因;已有失败任务只要保存了原始响应,升级插件后再次查询也会返回该原因,无需重新生成。
用量读取: 0 是有效值,缺省表示未提供,非法诊断值不返回。处理中用量未必完整,也不保证每次满足 withhold_token = actual_token + refund_token。以上字段均不是人民币金额;check_* 和 *_quota 不用于最终结算,实际费用以完成后的 actual_token 及平台结算记录为准,规则见第 5 节。
响应不返回 model,action_key / capability_key 也不是模型名;需要关联时自行保存 model 与 task_id。
临时原始视频地址 temporary_original_video_url 自生成后仅 24 小时 有效,平台不会续期或重新生成;正式对外分发、长期存档请使用 url。视频、封面和尾帧链接的有效期仍按即梦返回的地址规则处理,请及时下载到自己的存储。
2.3 Postman 测试流程
- 设置环境变量
BASE_URL和CHANNEL_API_TOKEN,分别填平台地址和自己的令牌;localhost仅适用于服务所在电脑。 - POST
{{BASE_URL}}/jimeng-agent/v1/tasks:Authorization 选 Bearer Token,填{{CHANNEL_API_TOKEN}};Body 选 raw → JSON,粘贴第 2.1 节示例并确认模型已开通。 - 保存响应的
data.task_id为TASK_ID。 - GET
{{BASE_URL}}/jimeng-agent/v1/tasks/{{TASK_ID}}:沿用鉴权,Body 选 none,按第 2.2.1 节轮询并获取结果。
若手动填写 Authorization: Bearer {{CHANNEL_API_TOKEN}} 请求头,Authorization 页选 No Auth,避免重复鉴权头。
3. 素材管理
3.1 使用流程与归属隔离
创建素材组 → 从 HTTP(S) URL 导入图片/视频/音频 → 保存 Id → 在生成任务中使用 asset://<Id>。普通 URL 也可直接用于生成,无需先导入。
请求约定: 全部使用 POST、JSON 和第 1.1 节的 Bearer Token。字段区分大小写,直接放在 Body 顶层,不套 input;只接受各接口列出的字段,不接受未知字段或 null,请求体上限 64 KiB。
素材库按平台用户隔离,不按令牌隔离。 同一用户更换令牌不改变归属;其他用户无法查看、修改、删除或引用,即使知道 ID 也只会收到“不存在或不可访问”的错误。
访问须符合当前令牌的有效分组(含 auto)、绑定渠道、允许模型及用户试用/正式模式。平台在列表筛选和每次上游操作前校验权限;权限变化后,游标从首页重查。
素材组与素材绑定创建时的上游账号,生成引用也固定该账号的渠道,不能混用不同账号的素材。试用转正式不自动迁移素材,历史归属不能绕过当前权限。
素材管理不扣账户余额或试用生成次数;视频生成按第 5 节执行。
3.2 数据结构
3.2.1 素材组 AssetGroup
| 字段 | 类型 | 说明 |
|---|---|---|
Id |
string | 素材组完整 ID,使用返回原值,不自行生成,不与素材 ID 混用 |
Name |
string | 素材组名称;允许同名,通过 ID 区分 |
Description |
string | 素材组描述 |
GroupType |
string | 组类型;当前仅开放创建 AIGC |
Unavailable |
boolean | 平台扩展字段;仅不可用时返回 true,表示即梦明确返回该组不存在或无法访问;保留原归属,可核对后恢复 |
CreateTime |
string | UTC RFC3339 创建时间,例如 2026-10-20T00:00:00Z |
UpdateTime |
string | UTC RFC3339 更新时间 |
3.2.2 素材 Asset
| 字段 | 类型 | 说明 |
|---|---|---|
Id |
string | 素材完整 ID,供查询、更新、删除及 asset:// 引用 |
GroupId |
string | 所属素材组 ID |
Name |
string | 展示名称;图片名称可能按上游规则去掉扩展名,以详情返回值为准 |
URL |
string | 当前可用的媒体访问链接,可能过期;使用时重新查询,长期引用保存 ID |
AssetType |
string | Image、Video 或 Audio |
Status |
string | 创建成功且可访问为 Active;平台核对后发现不存在或无法访问时为 Unavailable,保留归属但禁止生成引用 |
Moderation |
object | 审核信息 |
Moderation.Strategy |
string | 当前为 Default;创建时执行审核,不支持自定义审核策略 |
CreateTime |
string | UTC RFC3339 创建时间 |
UpdateTime |
string | UTC RFC3339 更新时间 |
素材导入同步完成校验与审核后才返回可用 ID,无需轮询 Processing;失败通过外层 code/message 返回。
3.2.3 素材接口公共响应
| 字段 | 类型 | 说明 |
|---|---|---|
code |
string | "0" 表示本次操作成功,其他值表示失败 |
message |
string | 操作结果或失败原因;客户端按错误码判断,不依赖完整文案 |
request_id |
string | 平台请求排查标识;出现错误时连同响应一起保存 |
upstream_request_id |
string | 可选,失败响应包含即梦请求标识时返回;与平台 request_id 分别保存 |
data |
object / null | 成功内容见各接口;失败时没有可用结果 |
创建与更新通常只返回 data.Id;完整对象及有效媒体 URL 通过详情接口获取。
3.3 列表筛选与分页
素材组与素材列表共用下表参数,仅查询当前用户有权访问的记录。
| 字段 | 类型 | 说明 |
|---|---|---|
Filter |
object | 必填,筛选对象 |
Filter.GroupType |
string | 必填;通常使用 AIGC。上游查询兼容 LivenessFace,不代表平台开放创建该类型 |
Filter.GroupIds |
string[] | 可选,最多 1000 个组 ID;省略或 [] 不额外限制组范围 |
Filter.Name |
string | 可选,名称包含匹配,最多 64 字符,去掉首尾空白;%、_ 视作普通字符,不是通配符 |
Filter.Statuses |
string[] | 仅素材列表可用,最多 3 项:Active、Processing、Failed;当前可见素材仅 Active |
SortBy |
string | 默认 CreateTime;组支持 CreateTime、UpdateTime,素材另支持 GroupId |
SortOrder |
string | Asc 或 Desc,默认 Desc |
PageNumber |
integer | 页码模式,从 1 开始,与 PageSize 一起传入 |
PageSize |
integer | 页码模式每页条数,1–100,与 PageNumber 一起传入 |
NextToken |
string | 游标模式;首页不传,续页使用上一页返回原值,不传空字符串 |
MaxResults |
integer | 游标模式每页条数,1–100,默认 10 |
条件间取交集,数组内按集合匹配;无结果时 Items=[]。仅筛选 Processing 或 Failed 时当前无可见素材。
页码与游标模式互斥。 PageNumber/PageSize 不能与 NextToken/MaxResults 混用,全部省略时按游标模式返回前 10 条。页码模式中,组列表 PageNumber × PageSize 不得超过 10,000,素材列表不得超过 20,000;更深数据使用游标模式。
| 模式 | data 返回字段 |
|---|---|
| 页码 | Items、PageNumber、PageSize、TotalCount |
| 游标 | Items;有下一页时返回 NextToken,无 TotalCount |
游标有效期 24 小时,续页须保持用户、接口、筛选、排序及每页条数一致;失效后从首页重查,不与即梦原始游标混用。
列表读取平台本地记录,跨页不保证快照一致。绕过平台上传的素材须经管理员同步、核对和分配,不会自动归属,也不能凭 ID 自行认领。
游标首页请求示例:
{ "Filter": { "GroupType": "AIGC" }, "MaxResults": 20 }
续页加上 "NextToken": "上一页返回的原值",不解析或修改游标。
3.4 素材组接口
3.4.1 创建素材组
POST {BASE_URL}/jimeng-agent/v1/asset_group/create
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Name |
string | 是 | 非空且不能全部为空白,最多 64 字符 |
Description |
string | 否 | 最多 300 字符,默认空字符串 |
GroupType |
string | 否 | 当前仅支持 AIGC;省略或空字符串按 AIGC 处理 |
{
"Name": "产品素材",
"Description": "用于产品短片的参考图片和视频",
"GroupType": "AIGC"
}
成功响应:
{
"code": "0",
"message": "success",
"request_id": "example-request-id",
"data": { "Id": "group-example" }
}
平台自动选择符合权限和使用模式的渠道,不接受渠道 ID 或模型字段;后续沿用该组绑定账号。允许同名组,通过返回的 Id 区分。
3.4.2 查询素材组列表
POST {BASE_URL}/jimeng-agent/v1/asset_group/list
参数见第 3.3 节,Filter.Statuses 不适用于组列表。
{
"Filter": { "GroupType": "AIGC", "Name": "产品" },
"PageNumber": 1,
"PageSize": 20,
"SortBy": "CreateTime",
"SortOrder": "Desc"
}
data.Items 为第 3.2.1 节的素材组数组,分页响应见第 3.3 节。
3.4.3 查询素材组详情
POST {BASE_URL}/jimeng-agent/v1/asset_group/get
请求:{ "Id": "group-example" }(必填字符串)。data 为素材组对象,不含组内素材;组内素材通过素材列表查询。
3.4.4 更新素材组
POST {BASE_URL}/jimeng-agent/v1/asset_group/update
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id |
string | 是 | 素材组完整 ID |
Name |
string | 否 | 最多 64 字符;传入时非空且不能全部为空白;省略表示不修改 |
Description |
string | 否 | 最多 300 字符;省略表示不修改,空字符串表示清空 |
{ "Id": "group-example", "Name": "新版产品素材", "Description": "" }
成功时返回 data.Id。不能用此接口修改 GroupType。
3.4.5 删除素材组
POST {BASE_URL}/jimeng-agent/v1/asset_group/delete
请求:{ "Id": "group-example" }。成功时 data 为 {}。
删除组会删除组内全部素材,之后不能查询或用于新任务,不会取消已受理任务。 同账号重复删除已删除的组可返回成功;未知或无权访问的组返回 20030。失败后仅对已确认归属的原 ID 重试。
3.5 素材接口
3.5.1 从 URL 导入素材
POST {BASE_URL}/jimeng-agent/v1/asset/create
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
GroupId |
string | 是 | 当前用户有权访问的素材组 ID,使用创建组接口的返回值 |
URL |
string | 是 | 即梦服务可直接访问的 HTTP(S) 媒体 URL;支持查询参数,不支持 asset://、URL 用户名密码或 fragment |
AssetType |
string | 是 | Image、Video 或 Audio,必须与实际媒体类型匹配 |
Name |
string | 否 | 最多 64 字符,可省略或传空字符串;实际展示名称以详情返回为准 |
{
"GroupId": "group-example",
"URL": "https://example.com/product.jpg",
"AssetType": "Image",
"Name": "产品正面"
}
成功时 data 为 { "Id": "asset-example" }。导入耗时取决于媒体大小和源站响应,无幂等字段,超时不要自动重试,先按第 3.8 节核对原组。
3.5.2 查询素材列表
POST {BASE_URL}/jimeng-agent/v1/asset/list
参数见第 3.3 节。按组查询示例:
{
"Filter": {
"GroupType": "AIGC",
"GroupIds": ["group-example"],
"Statuses": ["Active"]
},
"PageNumber": 1,
"PageSize": 20,
"SortBy": "CreateTime",
"SortOrder": "Desc"
}
data.Items 为第 3.2.2 节的素材数组,分页响应见第 3.3 节。
3.5.3 查询素材详情
POST {BASE_URL}/jimeng-agent/v1/asset/get
请求:{ "Id": "asset-example" }(必填字符串)。data 为素材对象;预览链接过期时通过此接口刷新 URL。
3.5.4 更新素材名称
POST {BASE_URL}/jimeng-agent/v1/asset/update
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id |
string | 是 | 素材完整 ID |
Name |
string | 否 | 最多 64 字符;省略表示不修改,空字符串表示清空名称 |
请求:{ "Id": "asset-example", "Name": "产品侧面" },成功返回 data.Id。不能修改 URL、AssetType、GroupId,更换文件须重新导入。
3.5.5 删除单个素材
POST {BASE_URL}/jimeng-agent/v1/asset/delete
请求:{ "Id": "asset-example" }。成功时 data 为 {}。
仅删除该素材,之后不能查询或用于新任务。已删除或无权访问时返回 20031,重复删除不保证成功。
3.5.6 导入媒体规格
按即梦下载后的媒体元信息校验,不按 URL 后缀判断;导入后用于生成仍须满足第 2.1.2 节的模型限制。
| 类型 | 规则 |
|---|---|
Image |
JPEG(含 JPG)、PNG、WebP、TIFF(含 TIF)、GIF、HEIC、HEIF;宽、高分别满足 300 < 边长 < 6000 像素;0.4 < 宽/高 < 2.5;0 < 文件大小 < 31,457,280 字节(30 MiB)。注意素材库规格未列出 BMP,不要从普通生成参数推断支持 |
Video |
MP4、MOV;时长 2–30 秒,包含边界,按毫秒精度校验;宽、高各 300–6000 像素,包含边界;总像素 407,696–8,295,044,包含边界;宽高比 0.4–2.5,包含边界;帧率 24–60 FPS,包含边界;0 < 文件大小 ≤ 209,715,200 字节(200 MiB) |
Audio |
WAV、MP3;时长 2–30 秒,包含边界,按毫秒精度校验;0 < 文件大小 ≤ 15,728,640 字节(15 MiB) |
3.6 在生成任务中引用素材
引用格式为 asset://<Id>,Id 必须是创建素材返回的完整字符串,例如 asset://asset-example。保留 ID 原样,不截取数字部分,不添加路径、端口、查询参数或 fragment;素材组 ID 不能替代素材 ID。
| 生成能力 | 支持字段 | 对应素材类型 |
|---|---|---|
短片创作 direct_model |
input.image_url_list / input.video_url_list / input.audio_url_list |
分别为 Image / Video / Audio |
营销视频 pippit_avatar_marketing_agent |
avatar_marketing_input.product_image_url_list / avatar_marketing_input.model_image_url_list |
Image |
剧情营销 pippit_story_marketing_agent |
avatar_marketing_input.product_image_url_list / avatar_marketing_input.model_image_url_list |
Image |
营销/剧情营销的完整任务接口不在本文范围内,须按平台开放的对应接口接入。
{
"model": "jimeng-agent-seedance25",
"input": {
"prompt": "以第一张图片中的产品为主体,参考第二张图片的场景生成短片",
"duration": 15,
"resolution": "720P",
"image_url_list": ["asset://asset-example", "https://example.com/scene.jpg"]
}
}
同一列表可混合 URL 与素材引用,顺序不变,数量及模型限制沿用原接口。引用必须属于当前用户、状态为 Active、类型与字段匹配,否则直接失败。
仅上表字段接受引用;创建素材的 URL、短剧 file_url、提示词等其他字段不支持。账号绑定与访问规则见第 3.1 节。
3.7 素材错误与重试
code |
含义 | 处理方式 |
|---|---|---|
10001 |
参数非法 | 检查必填、大小写、完整 ID、枚举、媒体规格及分页;过期或不匹配的上游游标也使用此码 |
20010 / 20011 / 20012 / 20013 |
音频 / 文本 / 图片 / 视频审核未通过 | 按具体 message 更换合规内容后重新请求 |
20030 |
素材组不存在或不可访问 | 检查当前用户归属、完整组 ID 及删除状态 |
20031 |
素材不存在或不可访问 | 检查当前用户归属、完整素材 ID 及删除状态;不泄露其他用户资源是否存在 |
20032 |
素材未就绪 | 确认详情 Status=Active 后再引用 |
50000 |
上游内部错误 | 保留 request_id;创建先核对结果,避免盲目重试 |
asset_mode_mismatch |
素材与当前用户使用模式或分组不匹配 | 使用符合当前试用/正式模式及分组的素材,不会自动迁移历史素材 |
asset_channel_mismatch |
同一任务引用了不同素材渠道下的资源 | 使用同一绑定渠道的素材;不能自动切换账号后继续生成 |
asset_account_changed |
素材绑定的即梦账号已变更 | 联系平台支持核对原账号,不要在新 AK/SK 下直接重用历史素材 ID |
channel_unavailable / no_available_channel |
素材渠道不存在、停用或无可用渠道 | 联系平台支持,保留原 ID;不要换另一个账号盲目重试 |
local_persistence_failed |
上游已创建但本地归属登记失败 | 不要重新创建,联系平台支持核对并恢复登记 |
upstream_invalid_response |
即梦返回结果无法识别 | 先核对操作是否成功,保留平台及即梦请求标识 |
upstream_result_unknown |
创建请求超时或连接中断,结果待确认 | 素材导入对原组执行第 3.8 节“核对上游”;新建组未获得 ID 时保留 request_id 联系管理员核对,不要重复创建 |
invalid_asset_reference |
素材引用格式或字段不合法 | 使用完整 asset://<Id>,仅放在支持的媒体列表中 |
asset_channel_conflict |
素材渠道与当前令牌或来源任务绑定渠道冲突 | 使用同一素材账号,不能通过其他渠道绑定覆盖素材归属 |
asset_service_unavailable |
素材权限校验服务暂时异常 | 保留原请求信息,稍后重试或联系平台支持,不绕过校验继续生成 |
其他网关错误见第 4 节。保留 HTTP 状态、code、message 和请求标识,不自动更换上游账号重试。
3.8 核对上游与异常恢复
POST {BASE_URL}/jimeng-agent/v1/asset_group/reconcile
导入超时后,用此接口检查原组,找回已导入但未登记的素材;控制台“刷新”只读取本地列表,不能确认上游导入结果。无组 ID 时联系平台支持,不凭同名判重、删除或认领。
{"Id":"完整素材组ID","PageNumber":1}
Id 为当前用户已拥有的组;PageNumber 默认 1,范围 1–1000。每页最多检查 20 个上游素材和 20 个本地素材,重合只查一次。固定使用组的绑定账号,权限沿用第 3.1 节,不接受用户、渠道或其他筛选;管理员“全部”视图也不能核对他人素材。
{
"code":"0",
"message":"success",
"request_id":"平台请求标识",
"data":{"Recovered":2,"Checked":20,"Unavailable":1,"NextPage":2}
}
| 返回字段 | 本页含义 |
|---|---|
Recovered |
找回并登记的素材数 |
Checked |
已核对数 |
Unavailable |
不可访问的本地素材数 |
NextPage |
下一页页码;缺省表示完成 |
有 NextPage 时用同一 Id 继续;失败可重试当前页,不重新导入。并发增删导致结果变化时,可从首页重查。
仅即梦明确返回 20030 / 20031 才标记不可用,保留记录及归属并禁止新引用;列表缺项、超时、5xx、无效响应不作为删除证据。有效详情可恢复素材;整组不可用时先核对恢复组访问,再逐页恢复素材。
4. 错误处理
程序按 code 判断错误,message 供展示和排查,不匹配完整文案。例如试用用户请求仅正式渠道可用的模型时返回 HTTP 503:
{
"code": "no_available_channel",
"message": "jimeng-agent-seedance25 是正式模型,试用分组的用户无法调用。 (request id: xxxxxxxxx)",
"data": null
}
任务错误使用 code/message/data;鉴权或权限检查也可能使用 error 结构,客户端须兼容并保留 HTTP 状态及响应体。
| 字段 | 类型 | 说明 |
|---|---|---|
code |
string | 请求错误码,例如 invalid_request、no_available_channel;与查询成功响应中的 data.err_code 区分 |
message |
string | 失败原因,可能附带 (request id: ...);成功响应可缺省 |
data |
null | 请求失败时没有任务结果;已有任务应继续使用原任务 ID 查询 |
error |
object | 替代外层结构;error.code 可空,error.message 为原因,可附 error.type(如 new_api_error) |
| HTTP 状态码 | 常见 code |
排查方向 |
|---|---|---|
| 400 | invalid_request |
JSON 格式、字段名、模型名、提示词或素材参数不合法,或时长、分辨率超出所选模型范围 |
| 401 | authentication_error |
缺少令牌、令牌错误或已失效 |
| 403 | model_not_allowed |
平台 API 令牌未获准使用该模型,检查令牌的可用模型限制 |
| 403 | insufficient_user_quota |
平台账户余额不足以支付本次预扣,提示中包含本次所需预扣金额,充值后重试 |
| 403 | insufficient_token_quota |
API 令牌额度不足;即使账户有余额,也需单独提高令牌额度 |
| 403 | insufficient_subscription_quota |
订阅额度不足或没有有效订阅 |
| 403 | token_quota_reservation_failed |
令牌预扣过程异常,请联系平台支持;不一定是余额不足 |
| 400 / 403 | channel_usage_mode_mismatch |
指定渠道与用户的试用/正式模式不一致 |
| 400 | model_price_error |
模型价格暂不可用,请联系平台支持 |
| 400 / 500 | channel_configuration_error |
渠道配置缺失或无效,请按 message 检查并联系平台支持 |
| 400 | usage_configuration_error |
模型用量估算失败,请联系平台支持 |
| 400 / 403 | channel_no_available_key / origin_task_channel_disabled |
渠道无可用密钥,或原任务渠道已停用 |
| 403 | permission_denied |
其他账号或令牌权限不足 |
| 404 | task_not_found |
任务 ID 不存在,或任务不属于当前账号 |
| 403 | trial_daily_quota_exhausted |
试用每日额度不足,北京时间次日 00:00 重置;如需调整请联系平台支持 |
| 503 | trial_quota_service_unavailable |
试用次数服务暂不可用,请稍后重试或联系平台支持 |
| 503 | no_available_channel |
无匹配的启用渠道;按用户模式、分组、模型和接口判断,不按模型或渠道名称判断 |
| 上游状态 / 502 | upstream_insufficient_quota |
上游渠道额度不足,请联系平台支持处理 |
| 上游状态 / 502 | upstream_permission_denied |
上游未开通模型或能力权限,请联系平台支持 |
| 上游状态 / 502 | upstream_authentication_failed |
上游鉴权失败,请联系平台支持 |
| 上游状态 / 502 | upstream_rate_limit_exceeded |
上游频率或并发限制,降低并发后再试 |
| 上游状态 / 502 | upstream_content_rejected |
上游内容审核不通过,调整提示词或素材 |
| 上游状态 / 502 | upstream_invalid_request |
上游拒绝参数,检查模型、时长、分辨率等约束 |
| 404 | upstream_not_found |
上游接口或模型不存在,请联系平台支持 |
| 500 / 408 / 504 | upstream_connection_error / upstream_timeout |
网络故障或超时,先确认上游是否受理再考虑重新创建 |
| 500 / 503 | upstream_unavailable |
上游服务暂时异常 |
| 502 等 | upstream_invalid_response |
上游返回异常数据或不可识别的失败原因,请联系平台支持 |
| 5xx | server_error |
未分类的内部故障;保留 request id 联系平台支持,接口不公开数据库细节、堆栈或密钥 |
上游 HTTP 200 的业务失败也可能映射为 HTTP 502;结合 code 判断,不能把所有 403 都当作令牌错误。
创建超时或 5xx 不等于未受理。 有任务 ID 时先查询;没有 ID 时保留请求标识联系支持,避免重复创建和扣费。查询短暂失败可延迟重试原 ID。
反馈问题时提供请求时间、model、脱敏参数、任务 ID、HTTP 状态和请求标识,隐藏 API 令牌及素材地址中的敏感信息。
5. 计费与试用
5.1 试用每日请求次数
试用默认每天 10 次创建/生成请求,配置为 0 时禁止生成;北京时间 00:00 重置。正式用户不受该次数限制。
试用只扣次数,不计算预扣、不校验余额,也不扣账户或 API 令牌额度。 仍需有效令牌、模型权限及试用渠道;上游用量仅供查看。
| 响应头 | 含义 |
|---|---|
X-Trial-Request-Limit |
每日上限 |
X-Trial-Request-Remaining |
本次扣减后剩余次数 |
X-Trial-Request-Reset |
下次重置的 Unix 秒数 |
额度不足返回 HTTP 403 和 trial_daily_quota_exhausted,不返回 Retry-After。每日额度按账户原子扣减,不限制请求频率或并发数;上游自身的频率限制仍按实际错误返回。并发响应可能乱序,勿仅按最后到达的值判断余量。
5.2 预扣费说明
以下规则仅适用于正式用户。
5.2.1 计费单位
平台按人民币计费,换算规则为:1 元人民币 = 100,000 token。实际费用 = 实际消耗 token ÷ 100,000。
5.2.2 预扣费用计算
| 任务类型 | 预扣金额 |
|---|---|
普通生成 / task_type=extend |
模型、分辨率对应单价(元/秒)× 目标时长(秒) |
Seedance 2.5 编辑:task_type=edit,或省略类型但传数字 duration=-1 |
固定 10 元;-1 不作为负时长参与计算 |
Seedance 2.5 样片转成片:仅传 input.draft_task_id |
Seedance 2.5 的 1080P 预扣单价(元/秒)× 15 秒估算时长 |
单价读取平台配置,调价不改变算法。普通生成 / 延长省略相应字段时,模型默认 Fast、分辨率默认 720P、时长默认 15 秒;延长仍须指定 Seedance 2.5。任务参数的默认与兼容规则见第 1.2.1、2.1.4 节。
Seedance 2.5 同时省略 task_type 和 duration 时,本地也按 15 秒估算,仅用于预扣,不向即梦补传时长,不凭提示词应用固定 10 元规则。
样片转成片的实际时长由即梦沿用样片;上述 1080P 与 15 秒只在平台本地用于预扣估算,不会补进上游请求,也不改变最终结算。管理员需配置 Seedance 2.5 的 1080P 预扣单价;实际费用仍按任务完成后的 usage.actual_token 多退少补。
提交即梦前校验并预扣余额。不足时返回 insufficient_user_quota 及所需金额,例如“本次任务预扣额度为 ¥10,账户额度不足,请充值后重试。”
5.2.3 多退少补
预扣款会在任务完成后按实际消耗重新结算。预扣金额高于实际费用时退回差额,实际费用高于预扣金额时补扣差额。
