端点参考 · 火山兼容接口(/api/v3)
用 /api/v3 迁移已有火山方舟 Seedance 视频生成接入。把 Base URL、API Key 和模型 ID 切换到 TokenPortal,按本页核对返回字段及接口差异。
创建任务并查询成片
先设置 TP_API_KEY 和新的 TP_REQUEST_ID,再从视频模型目录选择支持的 Seedance 模型 ID。成功生成可能产生费用。
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,有链接时及时下载。
curl "https://intertoken.ai/api/v3/contents/generations/tasks/TASK_ID" \
-H "Authorization: Bearer $TP_API_KEY"/api/v3 和 /v1 的幂等记录相互独立。超时后用同一个创建接口及原 Key、请求体、幂等键恢复,避免跨接口重发。回调目前不支持。
2. 你需要改的三样
| 改什么 | 火山方舟 | 本平台 |
|---|---|---|
| Base URL | https://ark.cn-beijing.volces.com/api/v3 | https://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 素材库是同一份数据,只是字段形状不同)
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[] 的图片位:
{
"type": "image_url",
"role": "reference_image",
"image_url": { "url": "asset://asset-xxxxxxxxxxxxxx-xxxxx" }
}- 不要把人像图片下载下来当普通图片传,它会被上游按「含真人面部」拒绝。
- 仅在所选路径支持此类公开素材时使用,任务费用以模型档位和平台用量记录为准。
7. 错误
所有错误都是火山形状:{"error": {"code", "message", "param", "type", "reason"}}(param / reason 有才出现;reason 放本平台原来的错误码,可以不读)。
| HTTP | code | type | 场景 |
|---|---|---|---|
| 400 | MissingParameter | BadRequest | 缺必填参数(缺 model;按秒计费的模型缺 duration 或不大于 0),param 为缺的字段 |
| 400 | InvalidParameter | BadRequest | 其它参数、内容或素材不合要求,能定位到字段时带 param |
| 400 | InvalidParameter.UnsupportedParameter | BadRequest | 传了 callback_url 或 priority |
| 401 | AuthenticationError | Unauthorized | 鉴权失败 |
| 403 | AccessDenied | Forbidden | IP 被临时封禁 |
| 403 | OperationDenied.UnsupportedPhase | — | 当前状态的任务不能取消,见 §5「取消 / 删除」 |
| 404 | InvalidEndpointOrModel.NotFound | NotFound | model 在本平台找不到可用货源 |
| 404 | NotFound | NotFound | 任务不存在、已过保留期、执行它的货源已删除,或不属于你的 Key(这几种响应完全相同) |
| 409 | Conflict | Conflict | 同一个 Idempotency-Key 正在处理中 |
| 429 | AccountRateLimitExceeded | TooManyRequests | 触发限流 |
| 500 | InternalServiceError | InternalServerError | 本平台或货源侧故障(不会出现 502 / 503),可稍后重试 |
参数或素材被字节原厂拒绝时,返回原厂的错误码与原因。