Seedance

兼容接入

使用 GlobalRouter 域名与 API Key 调用豆包兼容接口。按下方目录找到具体接口，再查看它的参数、请求示例和响应说明。

请按实际使用的站点选择 Base URL，后接各接口的完整路径：

https://api.globalrouter.com
https://api.globalrouter.ai

两个站点的数据不互通。请使用与你所在站点对应的 Base URL。下方示例默认使用 https://api.globalrouter.com。

参数	类型 / 位置	必填	说明
`Authorization`	请求头	是	Bearer <GlobalRouter API Key>，不要发送上游 X-Api-Key。
`Content-Type`	请求头	JSON 请求必填	application/json。
`Idempotency-Key`	GlobalRouter 扩展请求头	按接口要求	防止同一业务操作被重复提交。适用范围和重试规则见下方机制说明。

Idempotency-Key 机制

这是 GlobalRouter 新增的扩展请求头，不是火山原生接口参数。它用于识别同一次业务操作，避免客户端重复提交造成重复任务、训练或收费。它不用于鉴权，也不等同于任务 ID 或上游请求 ID。

参数	类型 / 位置	必填	说明
`字幕擦除、LAS 修复`	POST /doubao/api/v3/tools/…	是	1–128 个字符。
`音色分配、训练、升级`	POST voices / voice_clone / upgrade_voice	是	1–256 个字符。
`查询、TTS/ICL 流式合成及其他兼容接口`	按各接口约定	不要求此头	不能因为加了此头，就认为接口具备相同的去重或自动重试保证。

生成与保存

每个新的业务操作生成一个 UUID（例如 JavaScript 的 crypto.randomUUID()），并与业务记录一起保存；同一操作的重复请求必须复用原 key 和原参数。不同操作使用新 key，不要把示例中的占位值用于所有请求。不要每次 HTTP 尝试都重新生成 UUID。

Idempotency-Key: 6bcdfdf8-b94c-41d2-bc03-d6c604d4e40d

重复请求如何处理

同 key、同参数：关联原任务或原音色操作，读取已有结果或当前状态；不会重新提交已领取的上游操作。尚未得到确定结果时可能返回待处理错误，而不是成功响应。
同 key、不同参数：返回 409 冲突。字幕/LAS 为 MEDIA_IDEMPOTENCY_CONFLICT，音色训练/升级为 VOICE_OPERATION_CONFLICT；请核对业务记录，不要靠换 key 绕过冲突。
新业务操作：使用新 key，但仍需满足余额、权限及同音色操作互斥等条件。

超时和失败怎么办

例如训练请求超时，上游可能已收到音频。此时保留原 key，查询原音色操作或由管理员核验；不要换 key 再训练。同 key 的重复请求也不会强制重做结果未知的操作。只有确认原操作已结束、需要发起新的业务操作时才生成新 key。

已经取得媒体 task_id 时直接查询原任务。流式合成即使收到部分音频也不要自动重放文本；Idempotency-Key 不为流式合成提供重放保障。当前没有承诺固定的 key 过期或复用周期，请为新业务始终生成新 key。

记录按租户及对应业务范围隔离。两个 Base URL 的数据不互通，在另一个站点使用相同 key 不会找到本站原操作。

示例中的模型、任务、素材和音色标识以及 example.com 地址需替换为实际值。媒体接口的输出目录、任务标识及回调由平台管理，参数以各接口说明为准。

媒体能力

调用前须配置原账户凭据、模型权限和平台售价；LAS 还需同账户同地域的受管 TOS。

字幕擦除

POST /doubao/api/v3/tools/erase-video-subtitle-pro

按指定区域和时间段擦除字幕，返回平台异步任务。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`video_url`	string	是	可读取的 HTTP/HTTPS 视频地址。
`model_version`	string	否	v4 或 v5，默认 v4。
`mode`	string	否	Subtitle 或 Text，默认 Subtitle。
`output_encode_mode`	string	否	Quality 或 Size，默认 Quality。
`erase_ratio_location`	object[]	否	1–20 个矩形，top_left_x/y、bottom_right_x/y 为 0–1 坐标，右下角必须大于左上角。
`time_segment_filter`	object	否	mode 为 selected 或 skip；segments 中 start_time/end_time 为秒，结束大于开始。
`subtitle_filter`	object	否	min_text_height_ratio、max_text_height_ratio、center_offset_ratio 控制字幕筛选。

请求头必须携带 GlobalRouter 扩展头 Idempotency-Key。同一业务复用原 key；详见幂等机制与超时处理。

计费说明

场景	国内站	海外站	计费方式
字幕精细擦除	1 CNY/分钟	0.1389 USD/分钟	累计有效擦除秒数 ÷ 60

未指定 time_segment_filter 时按输出视频时长计费；指定 selected 时按合并重叠后的选中区间计费，指定 skip 时按输出时长减去跳过区间计费。时长精确到毫秒，累计后四舍五入。

示例：输出视频 90 秒且未指定区间，费用为 90 ÷ 60 × 1 = 1.5 CNY。区间 [0,20]、[15,30]、[60,75] 合并后为 45 秒，费用为 45 ÷ 60 × 1 = 0.75 CNY。

请求提交时冻结售价、折扣和汇率；最终金额以任务终态的有效计量证据及所在站点的实际配置为准。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tools/erase-video-subtitle-pro" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Idempotency-Key: replace-with-a-stable-operation-key' \
  -H 'Content-Type: application/json' \
  --data '{
  "video_url": "https://vod-ai-test.tos-cn-beijing.volces.com/demo/demo_video_drama_hard_subs.mp4"
}'

响应说明

请求示例使用火山引擎 AI MediaKit 字幕擦除指南提供的短剧硬字幕视频，可直接作为输入素材。按累计擦除时长计费；未指定时间段时按输出时长。client_token、callback_url、callback_args、queue_id 和输出目的地由平台管理，不能自行传入。

{
  "task_id": "37e3aecf-7aba-5c01-86da-440c9aac7907",
  "request_id": "37e3aecf-7aba-5c01-86da-440c9aac7907",
  "status": "pending",
  "output": [],
  "settlement": "pending",
  "error": null
}

水印去除与视频修复

POST /doubao/api/v3/tools/video-inpaint

使用 LAS 检测并修复视频中的水印或字幕。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`video_url`	string	是	可读取的 HTTP/HTTPS 视频地址。
`targets`	string[]	否	watermark、subtitle、scrolling_subtitle；默认仅 watermark。
`detection_precise_mode`	boolean	否	是否精准检测，默认 true；影响售价档位。
`inpainting_backend`	string	否	pixel_replace 为默认修复模式；官方动态水印示例使用 pixel_generate。模式影响价格与处理耗时，不保证每次自动检测均能去除目标。
`return_subtitle_bbox`	boolean	否	默认 true。
`max_process_frames`	integer	否	默认 -1，处理全部帧。正整数只处理指定帧数，例如 30fps 视频的 300 帧约为 10 秒。
`subtitle_mask_precise`	boolean	否	默认 false；主要用于白色、黄色字幕的精细遮罩，对透明、滚动字幕效果可能较差，不是水印检测开关。
`fixed_bboxes`	number[][]	否	格式 [[x1,y1,x2,y2]]，左上角为原点，坐标归一化至 0–1000；不是像素坐标。传入后仅修复指定区域，其他区域不会处理。

请求头必须携带 GlobalRouter 扩展头 Idempotency-Key。同一业务复用原 key；详见幂等机制与超时处理。

计费说明

场景	国内站	海外站	计费方式
普通检测 / pixel_replace	1.2 CNY/分钟	0.1667 USD/分钟	输出分钟 × 帧率折算系数
普通检测 / pixel_generate	1.6 CNY/分钟	0.2222 USD/分钟	输出分钟 × 帧率折算系数
精准检测 / pixel_replace	2.8 CNY/分钟	0.3889 USD/分钟	输出分钟 × 帧率折算系数
精准检测 / pixel_generate	3.2 CNY/分钟	0.4444 USD/分钟	输出分钟 × 帧率折算系数

帧率折算系数为 max(1, ceil(输出 fps ÷ 30))。31–60fps 的系数均为 2，不按输入视频或请求参数估算。

示例：60 秒、30fps、普通检测 + pixel_generate 为 1 × 1 × 1.6 = 1.6 CNY；同一视频为 60fps 时费用为 1 × 2 × 1.6 = 3.2 CNY。

请求提交时冻结售价、折扣和汇率；最终金额以任务终态的有效计量证据及所在站点的实际配置为准。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tools/video-inpaint" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Idempotency-Key: replace-with-a-stable-operation-key' \
  -H 'Content-Type: application/json' \
  --data '{
  "video_url": "https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/db283820bd07450abca6bff691acfef6~tplv-goo7wpa0wc-image.image",
  "targets": [
    "watermark"
  ],
  "detection_precise_mode": true,
  "inpainting_backend": "pixel_replace"
}'

固定位置水印：指定修复区域

适用于位置已知的固定水印，避免只依赖自动检测。以下区域覆盖示例视频左上角，坐标仅针对该素材，其他视频必须重新框选。换算：x / 视频宽度 × 1000，y / 视频高度 × 1000。传入 fixed_bboxes 后只处理框内区域；不要照搬去框选人脸、正文或字幕。实际效果请检查输出视频确认。

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tools/video-inpaint" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Idempotency-Key: replace-with-fixed-watermark-operation-key' \
  -H 'Content-Type: application/json' \
  --data '{
  "video_url": "https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/db283820bd07450abca6bff691acfef6~tplv-goo7wpa0wc-image.image",
  "targets": [
    "watermark"
  ],
  "detection_precise_mode": true,
  "inpainting_backend": "pixel_replace",
  "max_process_frames": -1,
  "fixed_bboxes": [
    [
      20,
      5,
      140,
      70
    ]
  ]
}'

动态水印：精准检测与生成式修复

参考官方动态水印示例，使用精准检测和 pixel_generate。将 video_url 替换为实际动态水印素材；水印会移动时不要只框住某一帧的位置。该模式的售价档位和耗时通常高于 pixel_replace；结果仍需逐段检查。

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tools/video-inpaint" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Idempotency-Key: replace-with-dynamic-watermark-operation-key' \
  -H 'Content-Type: application/json' \
  --data '{
  "video_url": "https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/db283820bd07450abca6bff691acfef6~tplv-goo7wpa0wc-image.image",
  "targets": [
    "watermark"
  ],
  "detection_precise_mode": true,
  "inpainting_backend": "pixel_generate",
  "max_process_frames": -1
}'

水印与字幕同时擦除

targets 同时选择 watermark 与 subtitle；仅选择 watermark 不要求删除底部字幕。滚动字幕请按素材改为 scrolling_subtitle。这里不传 fixed_bboxes，以免把处理范围限制在左上角。

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tools/video-inpaint" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Idempotency-Key: replace-with-watermark-subtitle-operation-key' \
  -H 'Content-Type: application/json' \
  --data '{
  "video_url": "https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/db283820bd07450abca6bff691acfef6~tplv-goo7wpa0wc-image.image",
  "targets": [
    "watermark",
    "subtitle"
  ],
  "detection_precise_mode": true,
  "inpainting_backend": "pixel_replace",
  "max_process_frames": -1
}'

响应说明

请求示例使用火山引擎 LAS 视频修复文档中的横版水印与字幕原始视频；当前 targets 仅擦除水印，如需同时擦除字幕可加入 subtitle。素材地址虽以 .image 结尾，实际返回 video/quicktime 视频，请保留完整地址。output_tos_path 由平台生成，不能指定任意桶或目录。用量为输出分钟 × max(1, ceil(fps/30))，具体价格按检测和修复模式匹配。 succeeded 表示处理与平台后处理完成，不保证视觉上所有水印均被移除。自动检测残留时，可对固定水印明确指定区域。修改参数进行新实验应使用新的 Idempotency-Key，同一请求重试才复用原 key；已有任务不会因修改示例而重新处理。

{
  "task_id": "37e3aecf-7aba-5c01-86da-440c9aac7907",
  "request_id": "37e3aecf-7aba-5c01-86da-440c9aac7907",
  "status": "pending",
  "output": [],
  "settlement": "pending",
  "error": null
}

查询媒体任务

GET /doubao/api/v3/tools/tasks/{task_id}

查询字幕或 LAS 平台任务的状态、结算状态和归档输出。

参数说明

参数	类型 / 位置	必填	说明
`task_id`	string · 路径	是	提交响应中的平台 task_id，不是上游任务 ID。

请求示例

curl -X GET "https://api.globalrouter.com/doubao/api/v3/tools/tasks/{task_id}" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY"

响应说明

status 表示处理状态，settlement 表示结算状态；output 为可用产物，error 为失败原因。下载地址有有效期；提交结果未知时保留原 ID，不重新 POST。

{
  "task_id": "37e3aecf-7aba-5c01-86da-440c9aac7907",
  "request_id": "37e3aecf-7aba-5c01-86da-440c9aac7907",
  "status": "pending",
  "output": [],
  "settlement": "pending",
  "error": null
}

TTS 与复刻音色合成

POST /doubao/api/v3/tts/unidirectional

合成文本，逐行返回 Base64 音频块及终态计量。

参数说明

参数	类型 / 位置	必填	说明
`X-Api-Resource-Id`	string · 请求头	是	公共音色用 seed-tts-2.0；复刻音色用 seed-icl-2.0。
`req_params.text`	string	是	非空待合成文本，UTF-8 最多 1 MiB。
`req_params.speaker`	string	是	公共目录音色 ID 或当前租户实际复刻音色代号。
`req_params.audio_params`	object	否	format: mp3/pcm/ogg_opus/wav，默认 mp3；可配置 sample_rate、bit_rate、speech_rate、loudness_rate、enable_subtitle。
`req_params.additions`	string	否	JSON 对象编码的字符串；扩展能力取决于 TTS/ICL 资源。

计费说明

场景	国内站	海外站	计费方式
公共 TTS 音色	0.0003 CNY/字符	0.00004167 USD/字符	终态 usage.text_words × 字符单价
复刻音色首次正式合成	138 CNY/音色 + 0.0003 CNY/字符	19.1667 USD/音色 + 0.00004167 USD/字符	首次槽位事件与正式字符用量齐全后结算
复刻音色后续正式合成	0.0003 CNY/字符	0.00004167 USD/字符	终态 usage.text_words × 字符单价

公共音色使用 seed-tts-2.0，不收槽位费；复刻音色使用 seed-icl-2.0。每个后付费复刻音色的槽位费只收一次，已有有效外部已付证明时不重复收取。

示例文本“你好，这是语音合成示例。”为 12 个 Unicode 字符：公共音色或已付槽位的复刻音色为 0.0036 CNY；首次正式使用复刻音色为 138.0036 CNY。最终字符数以上游终态 usage.text_words 为准。

请求提交时冻结售价、折扣和汇率；最终金额以任务终态的有效计量证据及所在站点的实际配置为准。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tts/unidirectional" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'X-Api-Resource-Id: seed-tts-2.0' \
  -H 'Content-Type: application/json' \
  --data '{
  "req_params": {
    "text": "你好，这是语音合成示例。",
    "speaker": "zh_female_vv_uranus_bigtts",
    "audio_params": {
      "format": "mp3"
    }
  }
}'

响应说明

这是逐行 JSON 流，不是直接返回 MP3。读取终态并检查 code 和 usage.text_words；缺用量时不重放文本。首次后付费 ICL 的槽位与字符证据齐全后一起结算。

{"code":0,"data":"<Base64 音频块>"}
{"code":20000000,"usage":{"text_words":12}}

查询音色目录

GET /doubao/api/v3/tts/voices?model=seed-tts-2.0&limit=50&offset=0

查询受管公共音色或本租户可用的复刻音色。

参数说明

参数	类型 / 位置	必填	说明
`model`	string · 查询	是	seed-tts-2.0 或 seed-icl-2.0。
`limit`	integer · 查询	否	1–100，默认 50。
`offset`	integer · 查询	否	从 0 开始，默认 0。

请求示例

curl -X GET "https://api.globalrouter.com/doubao/api/v3/tts/voices?model=seed-tts-2.0&limit=50&offset=0" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY"

响应说明

data 包含音色目录条目；复刻目录只返回本租户、原账户中已可用且没有未决操作的音色。

{
  "data": [],
  "limit": 50,
  "offset": 0
}

训练音色与自定义试听

POST /doubao/api/v3/tts/voice_clone

首次声音复刻只需上传一段音频，平台自动分配音色标识并训练，不需要传 speaker_id 或 custom_speaker_id。训练会同步显示在异步任务中，可选传入试听文本。

参数说明

参数	类型 / 位置	必填	说明
`audio.data`	string	是	音频 Base64，解码后非空且最大 10 MiB。
`audio.format`	string	建议填写	wav/mp3/ogg/m4a/aac/pcm；PCM、M4A 或无法识别头部时必须填写。
`text`	string	否	参考音频文本，最多 65536 字符。
`language`	integer	否	支持 0、1、2、3、4、5、8。
`extra_params.demo_text`	string	否	4–300 字符；后付费试听独立按实际字符计费。

请求头必须携带 GlobalRouter 扩展头 Idempotency-Key。同一业务复用原 key；详见幂等机制与超时处理。

计费说明

场景	国内站	海外站	计费方式
仅上传训练音频	不收费	不收费	未生成自定义试听字符
训练时传 demo_text	0.0003 CNY/字符	0.00004167 USD/字符	demo_text 的 Unicode 字符数 × 字符单价
播放已有试听链接	不收费	不收费	不产生新的合成用量

训练阶段不会收取首次槽位费。后付费音色首次用于 seed-icl-2.0 正式合成时，才按该接口的计费说明收取一次槽位费。

上游明确接受带 demo_text 的训练请求后结算试听字符费；明确拒绝时释放预占，结果未知时保留原操作等待恢复且不重新提交训练。

请求提交时冻结售价、折扣和汇率；最终金额以任务终态的有效计量证据及所在站点的实际配置为准。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tts/voice_clone" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Idempotency-Key: replace-with-a-stable-operation-key' \
  -H 'Content-Type: application/json' \
  --data '{
  "audio": {
    "data": "<替换为真实 WAV 文件的 Base64>",
    "format": "wav"
  },
  "extra_params": {
    "demo_text": "你好，这是自定义试听。"
  }
}'

已有音色重新训练（可选）

仅在需要重新训练已有音色时使用。后付费音色同时传 speaker_id（固定字符串 custom_speaker_id）和 custom_speaker_id（首次复刻返回的实际代号）；预付费音色仅传 speaker_id（已登记的音色 ID），省略 custom_speaker_id。其余音频及试听参数同上。一次新的重新训练使用新的幂等键；同一次请求重试复用原键及请求体。

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tts/voice_clone" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Idempotency-Key: replace-with-retrain-existing-voice-operation-key' \
  -H 'Content-Type: application/json' \
  --data '{
  "speaker_id": "custom_speaker_id",
  "custom_speaker_id": "gr0123456789abcdef0123456789abcdef",
  "audio": {
    "data": "<替换为真实 WAV 文件的 Base64>",
    "format": "wav"
  },
  "extra_params": {
    "demo_text": "你好，这是自定义试听。"
  }
}'

响应说明

首次复刻的请求无需音色 ID；响应中的 custom_speaker_id 是平台分配的结果，请保存用于后续查询和合成。只需要复刻时可省略 extra_params；需要自定义试听时传 extra_params.demo_text。上游接受训练后，试听按 demo_text 的 Unicode 字符数立即结算；播放已有试听链接不重复计费。训练和升级可在控制台异步任务中按音色 ID 查询。同一请求重试必须复用相同幂等键及请求体，避免分配新音色；同音色操作互斥，超时不应换键重训。

{
  "custom_speaker_id": "gr0123456789abcdef0123456789abcdef",
  "speaker_id": "gr0123456789abcdef0123456789abcdef",
  "status": 2,
  "speaker_status": [
    {
      "model_type": 4
    }
  ]
}

查询音色状态

POST /doubao/api/v3/tts/get_voice

查询原账户下音色的训练状态和试听信息。

参数说明

参数	类型 / 位置	必填	说明
`speaker_id`	string	是	后付费使用 custom_speaker_id 占位符；预付费填写已登记的音色 ID。
`custom_speaker_id`	string	后付费必填	平台分配的实际音色代号，必须与 speaker_id 占位符同时传入。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tts/get_voice" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "speaker_id": "custom_speaker_id",
  "custom_speaker_id": "gr0123456789abcdef0123456789abcdef"
}'

响应说明

status 0/1/2/3/4 表示未训练/训练中/成功/失败/已激活。可合成还需 ICL 模型效果状态 4 或 5；当前音色可用不能用于解除未知训练或升级的占用。

{
  "speaker_id": "gr0123456789abcdef0123456789abcdef",
  "status": 2,
  "speaker_status": [
    {
      "model_type": 4
    }
  ]
}

升级音色

POST /doubao/api/v3/tts/upgrade_voice

对当前租户音色执行独立、可选的升级操作。

参数说明

参数	类型 / 位置	必填	说明
`speaker_id`	string	是	后付费使用 custom_speaker_id 占位符；预付费填写已登记的音色 ID。
`custom_speaker_id`	string	后付费必填	平台分配的实际音色代号，必须与 speaker_id 占位符同时传入。

请求头必须携带 GlobalRouter 扩展头 Idempotency-Key。同一业务复用原 key；详见幂等机制与超时处理。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tts/upgrade_voice" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Idempotency-Key: replace-with-a-stable-operation-key' \
  -H 'Content-Type: application/json' \
  --data '{
  "speaker_id": "custom_speaker_id",
  "custom_speaker_id": "gr0123456789abcdef0123456789abcdef"
}'

响应说明

已满足 ICL 2.0 可用条件的音色无需先升级。升级须使用独立稳定幂等键；未知结果交由管理员核验原操作。

{
  "speaker_id": "gr0123456789abcdef0123456789abcdef",
  "status": 2,
  "speaker_status": [
    {
      "model_type": 4
    }
  ]
}

生成接口

创建视频生成任务

POST /doubao/api/v3/contents/generations/tasks

使用已开通的 Seedance 视频模型创建任务。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`model`	string	是	填写模型目录中已开通的视频模型 ID。
`content`	object[]	是	输入内容，如 {type:"text",text:"提示词"}；图片/视频内容及角色取决于所选模型。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "<已开通的 Seedance 模型 ID>",
  "content": [
    {
      "type": "text",
      "text": "日落时分，镜头缓慢掠过海面。"
    }
  ]
}'

响应说明

保存返回的 id，用查询视频生成任务接口读取结果。其他参数及模型限制以所选模型说明为准；发生提交超时不要盲目重新生成。

{
  "id": "<视频任务 ID>"
}

查询视频生成任务

GET /doubao/api/v3/contents/generations/tasks/{task_id}

查询原视频生成任务。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`task_id`	string · 路径	是	创建视频任务返回的 id。

请求示例

curl -X GET "https://api.globalrouter.com/doubao/api/v3/contents/generations/tasks/{task_id}" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY"

响应说明

status 为任务状态；成功时读取 content.video_url，失败时检查 error。此接口用于 Seedance 生成任务，不能用于字幕/LAS 的平台任务查询。

{
  "id": "<视频任务 ID>",
  "status": "succeeded",
  "content": {
    "video_url": "https://example.com/result.mp4"
  }
}

图片生成

POST /doubao/api/v3/images/generations

使用已开通的 Seedream 模型生成图片。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`model`	string	是	填写模型目录中已开通的 Seedream 模型 ID。
`prompt`	string	是	图片描述。
`size`	string	否	图片尺寸；支持范围取决于所选模型。
`response_format`	string	否	url 或 b64_json，按模型支持情况使用。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/api/v3/images/generations" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "<已开通的 Seedream 模型 ID>",
  "prompt": "清晨的海边小屋，写实摄影",
  "response_format": "url"
}'

响应说明

读取 data 中的图片地址或 Base64；临时地址应及时保存。

{
  "data": [
    {
      "url": "https://example.com/result.png"
    }
  ]
}

多模态向量化

POST /doubao/api/v3/embeddings/multimodal

对文本、图片或视频输入生成多模态向量。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`model`	string	是	已开通的多模态向量模型。
`input`	object[]	是	按 type 提供 text、image_url 或视频输入；结构由模型定义。
`encoding_format`	string	否	示例使用 float。
`dimensions`	integer	否	输出维度，须为所选模型支持值。
`sparse_embedding`	object	否	稀疏向量配置，如 {type:"disabled"}。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/api/v3/embeddings/multimodal" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "doubao-embedding-vision-251215",
  "input": [
    {
      "type": "text",
      "text": "图片中的建筑是什么？"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/tower.png"
      }
    }
  ],
  "encoding_format": "float",
  "dimensions": 1024,
  "sparse_embedding": {
    "type": "disabled"
  }
}'

响应说明

返回模型原生向量结果。OpenAI 兼容 embeddings 入口只接受文本；混合输入使用本接口。

SeedAudio 1.0 音频生成

POST /doubao/api/v3/tts/create

根据文本及参考资源生成音频。

接口约定

请求体与火山引擎 SeedAudio 1.0 保持一致。将域名替换为 GlobalRouter，使用Authorization: Bearer <GlobalRouter API Key> 鉴权。GlobalRouter 服务端默认选择独立的doubao_audio Provider 及其上游凭据。

方法	POST
路径	/doubao/api/v3/tts/create
模型	doubao-seed-audio-1-0
上游模型映射	seed-audio-1.0
Provider	GlobalRouter 服务端默认选择独立的 doubao_audio Provider；请求体无需且不应传入 provider。
鉴权边界	只发送 GlobalRouter Bearer Key，不要发送上游 X-Api-Key。
按量价格	1 元/分钟
计费时长	按 original_duration 计费，倍速不影响计费时长。

参数说明

字段	必填	说明
model	是	固定使用 doubao-seed-audio-1-0；也兼容官方 seed-audio-1.0 别名。
text_prompt	是	待合成文本或生成提示，最多 3000 字符；音频参考可用 @音频N 按顺序引用。
references	否	参考资源列表。音频使用 speaker、audio_data 或 audio_url；图片使用 image_data 或 image_url。
audio_config	否	支持 format、sample_rate、speech_rate、loudness_rate、pitch_rate、enable_subtitle。
watermark	否	水印对象，支持 aigc_watermark 和 aigc_metadata。

参考资源限制

最多 3 条参考音频，每条最长 30 秒、最大 10 MB；支持 wav、mp3、pcm、ogg_opus。
仅支持 1 张参考图片，最大 10 MB；支持 jpeg、png、webp。
音频参考与图片参考不能混用；speaker、audio_data、audio_url 三选一，image_data、image_url 二选一。

响应说明

字段	说明
code / message	上游业务状态。非零 code 会映射为稳定的 SeedAudio Provider 错误。
audio	Base64 编码的音频内容。
url	上游临时下载地址，URL 有效期为 2 小时。
duration	变速或后处理后的音频时长（秒）。
original_duration	模型输出的原始音频时长，最长 120 秒，并以此字段计费。
subtitle	开启 enable_subtitle 后返回，包含 text、sentences 和 words 的毫秒级时间戳。
X-Tt-Logid	响应头中的火山引擎请求追踪 ID。

请求示例

纯文本请求示例

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tts/create" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-audio-1-0",
    "text_prompt": "生成一段舒缓的钢琴曲，氛围柔和、放松。",
    "audio_config": {
      "format": "mp3",
      "enable_subtitle": true
    }
  }'

音频参考请求示例

请将参考资源 URL 替换为上游能够访问的真实公网地址。

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tts/create" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-audio-1-0",
    "text_prompt": "参考 @音频1 的风格，生成一段舒缓钢琴曲",
    "references": [{
      "audio_url": "https://example.com/reference.mp3"
    }],
    "audio_config": {
      "format": "mp3",
      "sample_rate": 48000,
      "speech_rate": 0,
      "loudness_rate": 0,
      "pitch_rate": 0,
      "enable_subtitle": true
    }
  }'

图片参考请求示例

curl -X POST "https://api.globalrouter.com/doubao/api/v3/tts/create" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-audio-1-0",
    "text_prompt": "根据图片氛围朗读：清晨，海边吹来温柔的风。",
    "references": [{
      "image_url": "https://example.com/reference.webp"
    }],
    "audio_config": {"format": "mp3"}
  }'

响应示例

{
  "code": 0,
  "message": "success",
  "audio": "<base64-audio>",
  "duration": 12.4,
  "original_duration": 12.4,
  "url": "https://example.com/generated.mp3",
  "subtitle": {
    "text": "清晨，海边吹来温柔的风。",
    "sentences": [{
      "start_time": 0,
      "end_time": 12400,
      "text": "清晨，海边吹来温柔的风。",
      "words": [{"start_time": 0, "end_time": 600, "text": "清晨"}]
    }]
  }
}

注意事项

只提交 GlobalRouter 鉴权

请求体无需且不应传入 provider。不要发送上游 X-Api-Key，也不要在请求体中传入 api_key、ApiKey 或 Authorization。GlobalRouter 服务端固定使用 doubao_audio Provider 及平台配置的服务端密钥访问上游，并递归移除请求体中的鉴权字段。

官方参数和限制请以火山引擎接口文档为准；价格与计费口径请参见火山引擎计费说明。

素材接口

素材 Action 统一使用 /doubao/ 路径和 Version=2024-01-01。虚拟人像与真人人像共用素材管理接口，真人人像先完成认证并取得分组。

素材使用前请确认审核状态与项目归属

素材需要审核通过后（Active）才可以使用。生成视频必须使用素材所在项目中的推理接入点。

素材接口说明附件

创建素材分组

POST /doubao/?Action=CreateAssetGroup&Version=2024-01-01

虚拟人像与真人人像共用此 Action，平台按租户校验资源归属。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`Name`	string	是	分组名称。
`GroupType`	string	是	虚拟人像使用 AIGC；真人人像通过认证结果建立分组。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "Name": "演示分组",
  "GroupType": "AIGC"
}'

响应说明

返回创建的分组标识，后续上传通过 GroupId 关联。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

上传素材

POST /doubao/?Action=CreateAsset&Version=2024-01-01

虚拟人像与真人人像共用此 Action，平台按租户校验资源归属。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`GroupId`	string	否	当前租户拥有的分组 ID；真人人像使用认证得到的分组。
`URL`	string	是	可读取的素材公网 URL。
`AssetType`	string	是	图片使用 Image。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "GroupId": "<素材分组 ID>",
  "URL": "https://example.com/portrait.png",
  "AssetType": "Image"
}'

响应说明

返回素材标识；使用前查询审核状态，Active 才可用于生成。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

查询素材分组列表

POST /doubao/?Action=ListAssetGroups&Version=2024-01-01

虚拟人像与真人人像共用此 Action，平台按租户校验资源归属。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`GroupType`	string	否	AIGC 或 LivenessFace，按素材类型选择。
`PageNumber / PageSize`	integer	否	分页参数，示例使用第 1 页、每页 10 条。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=ListAssetGroups&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "GroupType": "AIGC",
  "PageNumber": 1,
  "PageSize": 10
}'

响应说明

返回本租户拥有的分组列表及分页信息。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

查询素材列表

POST /doubao/?Action=ListAssets&Version=2024-01-01

虚拟人像与真人人像共用此 Action，平台按租户校验资源归属。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`GroupIds`	string[]	否	按当前租户拥有的分组过滤。
`Statuses`	string[]	否	按审核状态过滤。
`Name`	string	否	按名称过滤。
`PageNumber / PageSize`	integer	否	分页参数。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=ListAssets&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "GroupIds": [
    "<素材分组 ID>"
  ],
  "PageNumber": 1,
  "PageSize": 10
}'

响应说明

返回当前租户素材及分页信息。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

查询素材详情

POST /doubao/?Action=GetAsset&Version=2024-01-01

虚拟人像与真人人像共用此 Action，平台按租户校验资源归属。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`Id`	string	是	本租户素材 ID。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "Id": "<素材 ID>"
}'

响应说明

返回原素材详情及审核状态。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

更新素材

POST /doubao/?Action=UpdateAsset&Version=2024-01-01

虚拟人像与真人人像共用此 Action，平台按租户校验资源归属。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`Id`	string	是	本租户素材 ID。
`Name`	string	否	新的素材名称。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=UpdateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "Id": "<素材 ID>",
  "Name": "更新后的素材名称"
}'

响应说明

返回上游更新结果；修改前校验租户归属。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

删除素材

POST /doubao/?Action=DeleteAsset&Version=2024-01-01

虚拟人像与真人人像共用此 Action，平台按租户校验资源归属。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`Id`	string	是	本租户素材 ID。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=DeleteAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "Id": "<素材 ID>"
}'

响应说明

返回删除结果；成功后清除平台素材归属。删除前确认没有在用的引用。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

查询素材分组详情

POST /doubao/?Action=GetAssetGroup&Version=2024-01-01

虚拟人像与真人人像共用此 Action，平台按租户校验资源归属。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`Id`	string	是	本租户分组 ID。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=GetAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "Id": "<素材分组 ID>"
}'

响应说明

返回分组详情，查询前校验租户归属。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

更新素材分组

POST /doubao/?Action=UpdateAssetGroup&Version=2024-01-01

虚拟人像与真人人像共用此 Action，平台按租户校验资源归属。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`Id`	string	是	本租户分组 ID。
`Name`	string	否	新的分组名称。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=UpdateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "Id": "<素材分组 ID>",
  "Name": "更新后的分组名称"
}'

响应说明

返回上游更新结果，修改前校验租户归属。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

删除素材分组

POST /doubao/?Action=DeleteAssetGroup&Version=2024-01-01

虚拟人像与真人人像共用此 Action，平台按租户校验资源归属。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`Id`	string	是	本租户分组 ID。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=DeleteAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "Id": "<素材分组 ID>"
}'

响应说明

返回删除结果；成功后清除平台分组归属。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

创建真人人像认证会话

POST /doubao/?Action=CreateVisualValidateSession&Version=2024-01-01

用于真人人像授权与素材分组绑定。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`CallbackURL`	string	按业务配置	接收认证结果的 HTTPS 回调地址。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "CallbackURL": "https://example.com/verification/callback"
}'

响应说明

读取 Result 中的 BytedToken 和认证链接，完成真人授权。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

查询真人人像认证结果

POST /doubao/?Action=GetVisualValidateResult&Version=2024-01-01

用于真人人像授权与素材分组绑定。

官方文档

参数说明

参数	类型 / 位置	必填	说明
`BytedToken`	string	是	认证会话返回的 BytedToken。
`ProjectName`	string	否	素材所属项目；未提供时使用配置项目，生成视频须使用同项目接入点。

请求示例

curl -X POST "https://api.globalrouter.com/doubao/?Action=GetVisualValidateResult&Version=2024-01-01" \
  -H "Authorization: Bearer $GLOBALROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "BytedToken": "<认证会话 Token>"
}'

响应说明

认证成功时返回分组标识并绑定当前租户；未返回分组不代表已完成认证。素材 Action 返回上游原生响应；具体业务字段随 Action 不同，不按普通媒体任务结构解析。

音色与媒体计费

场景	计费单位	参考价格（CNY）	约合美元（USD）
字幕精细擦除	`minute`	1	0.1389
LAS 普通检测 / pixel_replace	`minute`	1.2	0.1667
LAS 普通检测 / pixel_generate	`minute`	1.6	0.2222
LAS 精准检测 / pixel_replace	`minute`	2.8	0.3889
LAS 精准检测 / pixel_generate	`minute`	3.2	0.4444
TTS 正式字符	`character`	0.0003	0.00004167
ICL 正式字符	`character`	0.0003	0.00004167
后付费训练试听字符	`character`	0.0003	0.00004167
首次后付费槽位	`voice_slot`	138	19.1667

按 1 USD ≈ 7.2 CNY 换算，仅供参考，实际扣费以平台配置为准。

视频按实际计费用量折算；字符按实际用量计费；首次后付费槽位仅在触发首次收费时计收。

文件接口

上传文件

POST /doubao/api/v3/files

使用 GlobalRouter API Key 上传文件或文件 URL，表单参数透传给方舟，不收取平台费用。

官方文档

查询文件

GET /doubao/api/v3/files/{file_id}

根据文件 ID 查询方舟文件状态，返回方舟原始结果。

官方文档