logo数金Token

即梦 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 测试流程

  1. 设置环境变量 BASE_URL 和 CHANNEL_API_TOKEN,分别填平台地址和自己的令牌;localhost 仅适用于服务所在电脑。
  2. POST {{BASE_URL}}/jimeng-agent/v1/tasks:Authorization 选 Bearer Token,填 {{CHANNEL_API_TOKEN}};Body 选 raw → JSON,粘贴第 2.1 节示例并确认模型已开通。
  3. 保存响应的 data.task_id 为 TASK_ID。
  4. 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 多退少补

预扣款会在任务完成后按实际消耗重新结算。预扣金额高于实际费用时退回差额,实际费用高于预扣金额时补扣差额。