端点参考 · 火山兼容接口(/api/v3)

The guide below is in Chinese.

用 /api/v3 迁移已有火山方舟 Seedance 视频生成接入。把 Base URL、API Key 和模型 ID 切换到 TokenPortal,按本页核对返回字段及接口差异。

创建任务并查询成片

先设置 TP_API_KEY 和新的 TP_REQUEST_ID,再从视频模型目录选择支持的 Seedance 模型 ID。成功生成可能产生费用。

Shell command
curl "https://intertoken.ai/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $TP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $TP_REQUEST_ID" \
  -d '{"model":"MODEL_ID","content":[{"type":"text","text":"海边日落"}],"duration":5}'

保存响应的 id 并替换下例的 TASK_ID。成功后读取 content.video_url,有链接时及时下载。

Shell command
curl "https://intertoken.ai/api/v3/contents/generations/tasks/TASK_ID" \
  -H "Authorization: Bearer $TP_API_KEY"

/api/v3 和 /v1 的幂等记录相互独立。超时后用同一个创建接口及原 Key、请求体、幂等键恢复,避免跨接口重发。回调目前不支持。

2. 你需要改的三样

改什么火山方舟本平台
Base URLhttps://ark.cn-beijing.volces.com/api/v3https://intertoken.ai/api/v3
API Key火山方舟 API Key本平台 sk- Key,Authorization: Bearer sk-…(见 API Key 与鉴权)
model火山模型名(如 doubao-seedance-2-0-260128)或接入点 ID(ep-…)本平台模型名,从模型目录取。火山模型名与 ep-… 接入点 ID 在本平台查不到,会返回 404

注意 Base URL 不带 /v1:它是数据面地址去掉末尾 /v1 后再接 /api/v3。

其它创建参数(content[]、role、resolution、ratio、duration、generate_audio、return_last_frame 等)原样传,各参数在本平台的取值范围以创建生成任务与该模型的 schema 为准。

3. 目前开放的接口

视频任务

火山方舟接口本平台 /api/v3
创建任务 POST /contents/generations/tasks✅
查询任务 GET /contents/generations/tasks/{id}✅
查询任务列表 GET /contents/generations/tasks✅(差异见 §5「任务列表」)
取消或删除任务 DELETE /contents/generations/tasks/{id}✅(差异见 §5「取消 / 删除」)

素材库(与 /v1 素材库是同一份数据,只是字段形状不同)

Code
POST   /api/v3/media/assets            # 注册
GET    /api/v3/media/assets/{id}       # 单查(带上游签发的临时地址)
GET    /api/v3/media/assets            # 列表
PATCH  /api/v3/media/assets/{id}       # 改名(PUT 同义)
DELETE /api/v3/media/assets/{id}       # 删除

请求与返回用火山素材接口的 PascalCase 字段(URL / AssetType / Name)。

4. 返回体

创建:{"id": "<任务ID>"},与火山相同,只有这一个键。

查询:火山文档《查询视频生成任务》里出现的每个字段都会出现,字段名、位置、类型与火山一致:

id · model · status · content.video_url · content.last_frame_url · created_at · updated_at · duration · frames · framespersecond · ratio · resolution · seed · generate_audio · output_format · service_tier · execution_expires_after · safety_identifier · priority · draft · draft_task_id · tools · usage.completion_tokens · usage.total_tokens · usage.tool_usage · error

需要知道的差异:

  • 键恒在,取不到时值为 null。火山对部分字段是「有才返回」(如 duration 与 frames 只回一个、未用工具时不回 tools),本平台一律返回这个键。所以请判断值是不是 null,不要用「键在不在」做分支——if "tools" in resp 在本平台恒为真。content 与 usage 恒为对象,排队中也可以直接读 content.video_url(值为 null)。
  • 状态词与火山相同:queued / running / succeeded / failed / cancelled / expired。
  • error:failed 时为 {"code", "message", "reason"}。报错来自字节原厂时,code 与 message 是原厂原文;渠道只转来原文、没带错误码时,code 填 InternalServiceError,message 仍是原厂原文。所以不要凭 code=InternalServiceError 断定 message 是固定句子,请读 message。expired 与 cancelled 时 error 也是对象(如 {"code": null, "message": null, "reason": "upstream_expired"}),不代表失败,请以 status 判断结局。reason 是本平台附加的分类字段,可以不读。
  • priority 只读:创建时传入返回 400;响应里的 priority 是执行该任务的货源实际使用的值,取不到时为 null。
  • created_at:Unix 秒(UTC),恒出现。优先取上游返回的创建时刻,上游没给时用本平台受理时刻。不要从任务号里解析时间——任务号的编号规则属于上游,本平台不保证它的含义与稳定性。
  • 多出来的键:output、echo 是本平台附加的,不读不影响。echo 可能整体不出现,读之前先判断它存在。
  • 不同模型的字段完整度不同:部分货源不提供某些字段(例如尾帧、seed、原厂任务号),这些字段会是 null。

怎样判断拿到的是字节原厂任务号 / 原厂链接

  • 原厂任务号:以 cgt- 开头的才是。拿得到时顶层 id 就是它(见 §5「任务 ID」),请以顶层 id 为准;顶层 id 不是 cgt- 开头,说明该任务目前拿不到原厂任务号。echo.upstream_task_id 只反映本次上游响应,可能缺失,不要依赖它。
  • 原厂链接:域名属于火山引擎(volces.com)签发的才是。先看 echo.upstream_url,再看 content.video_url;两处都不是,说明该任务拿不到原厂链接。产物链接的域名由执行任务的货源决定,本平台不做统一转存。

5. 与火山方舟不同的地方

项本平台行为
任务 ID保留创建响应中的 id 继续查询。这个 ID 不适合用来判断任务时刻或完成状态。
保留期平台任务记录从创建起保留 7 天,上游查询窗口与视频链接有效期各自计算,可能更短。任务完成后请及时下载。
任务列表参数与火山同名:page_num(1–500,默认 1)、page_size(1–500,默认 20)、filter.status、filter.task_ids(可重复,创建时的 id 与 cgt-… 都认)、filter.model、filter.service_tier(本平台无此维度,传了会被忽略)。越界或取值非法返回 400、code=InvalidParameter,param 为该参数。返回 {"items": [...], "total": N},按创建时间倒序,每项与单任务查询的形状相同。与火山不同的三点:① filter.model 填本平台模型名,按与创建时 model 完全相同的字符串匹配(创建时用的是别名,筛选也要填同一个别名);② 只列出你这个 API Key 创建的任务,2026-09-22 14:13 UTC 之前创建的任务不在列表里(单任务查询照常可查);③ 未结束任务的状态可能比单任务查询滞后,filter.status 按刷新前记下的状态筛选,返回项的 status 可能与筛选条件不一致。需要实时状态请用单任务查询
取消 / 删除本平台先查一次任务最新状态再处理:排队中的任务,仅当由火山直连执行时可以取消(返回 200 {},之后查询为 cancelled;火山拒绝取消时原样返回火山的状态码与错误);其它渠道的排队中任务,以及运行中、已取消的任务,返回 403、code=OperationDenied.UnsupportedPhase。已成功 / 已失败 / 已过期的任务:删除本平台的任务记录,返回 200 {},之后查询为 404(工作台作品库不受影响)。当时查不到任务最新状态,或任务已成功但本平台尚未完成计费时,返回 500、code=InternalServiceError,可稍后重试;若该任务用量始终为 0 则无法删除,记录会在 7 天保留期结束后自动清除。任务不存在、已过保留期或不属于你的 Key,返回 404
素材列表分页两套,与火山同名:页码模式 PageNumber + PageSize,回 TotalCount(全量总数,不是本页条数)/ PageNumber / PageSize;游标模式 MaxResults,回 NextToken(原样带进下一次请求;没有下一页时这个键不出现)。两套的回显字段互不混发,请按你用的那套判断有没有下一页
素材下载地址(URL)列表里的 URL 为 null。单查可取得临时地址时,请即取即用。不能提供预览的素材单查也可能返回 null,这时仍可通过已有素材 ID 引用。
callback_url / priority创建时传入返回 400、code=InvalidParameter.UnsupportedParameter,param 为该字段名
safety_identifier由平台按计费主体填写,你传的值会被覆盖
asset:// 素材 ID火山公共素材与预置虚拟人像的 asset:// ID 可以直接用(见下方 §6);你自己火山账号里的私有 asset:// 素材,上游通过本平台看不到
Idempotency-Key 请求头(本平台扩展)可选,语义同创建生成任务。/api/v3 与 /v1 的幂等记录互相独立:同一个 Idempotency-Key 在两条路径上各发一次,会创建两个任务、各计一次费。处理中重复提交返回 409、code=Conflict——火山不会返回 409,按状态码做白名单的客户端请把它纳入
图片 / 视频 / 音频的传法推荐使用公网可下载的 URL。Base64 data URI 支持范围以实际模型为准。收到 asset_required 后按素材库说明登记。
首帧图生视频不要传 ratio:输出比例跟随首帧图,传了会被上游拒绝;返回的 ratio 可能是图片自身的比例(如 "425:241")。参考图受上游真人审核,可能被拒
配音(generate_audio)是否支持以及默认值以模型参数 Schema 为准。
output_format原样透传给上游,但可能不被兑现(实测请求 "mov"、返回 "mp4")。请以响应里的 output_format 与产物后缀为准
请求的 User-Agent若 HTTP 客户端遇到入口防护返回的 403 或 1010,请先确认请求头,再按返回内容排查。

6. 用火山虚拟人像:直接填 asset:// ID

火山方舟体验中心提供一批公开的虚拟人像(合成形象,不对应真人)。登录火山账号进入方舟体验中心的「虚拟人像库」,复制 asset ID,填进 content[] 的图片位:

JSON
{
  "type": "image_url",
  "role": "reference_image",
  "image_url": { "url": "asset://asset-xxxxxxxxxxxxxx-xxxxx" }
}
  • 不要把人像图片下载下来当普通图片传,它会被上游按「含真人面部」拒绝。
  • 仅在所选路径支持此类公开素材时使用,任务费用以模型档位和平台用量记录为准。

7. 错误

所有错误都是火山形状:{"error": {"code", "message", "param", "type", "reason"}}(param / reason 有才出现;reason 放本平台原来的错误码,可以不读)。

HTTPcodetype场景
400MissingParameterBadRequest缺必填参数(缺 model;按秒计费的模型缺 duration 或不大于 0),param 为缺的字段
400InvalidParameterBadRequest其它参数、内容或素材不合要求,能定位到字段时带 param
400InvalidParameter.UnsupportedParameterBadRequest传了 callback_url 或 priority
401AuthenticationErrorUnauthorized鉴权失败
403AccessDeniedForbiddenIP 被临时封禁
403OperationDenied.UnsupportedPhase—当前状态的任务不能取消,见 §5「取消 / 删除」
404InvalidEndpointOrModel.NotFoundNotFoundmodel 在本平台找不到可用货源
404NotFoundNotFound任务不存在、已过保留期、执行它的货源已删除,或不属于你的 Key(这几种响应完全相同)
409ConflictConflict同一个 Idempotency-Key 正在处理中
429AccountRateLimitExceededTooManyRequests触发限流
500InternalServiceErrorInternalServerError本平台或货源侧故障(不会出现 502 / 503),可稍后重试

参数或素材被字节原厂拒绝时,返回原厂的错误码与原因。

下一步

返回视频接入指南 · 查看 /v1 的创建与查询 · 查询平台错误码