身份验证
在请求头中携带当前账户生成的 Bearer API Key。
Authorization: Bearer YOUR_API_KEY模型列表
/v1/modelscurl /v1/models \
-H "Authorization: Bearer YOUR_API_KEY"调用额度
/v1/limits返回当前用户的并发上限、排队上限、进行中及排队数量，以及剩余点数。每个任务按当前用户对应模型的价格预扣点数，价格在任务创建时固定（模型列表的 point_cost 字段）；任务失败或取消按原扣款点数返还。充值基础兑换为 1 元 = 1 点，到账点数乘以用户充值系数。
创建视频
/v1/videos先从模型列表选择可用模型。视频生成是异步任务，创建成功会返回 HTTP 202；保存返回的 id 或 task_id 后查询结果。参考素材可同时使用图片、视频和音频公网 URL；素材地址必须能被本服务访问，不能是本机路径或依赖登录 Cookie 的地址。
curl /v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_VIDEO_MODEL_ID",
"prompt": "参考图片中的产品、参考视频的镜头运动和参考音频的节奏，生成约 5 秒的产品视频",
"seconds": 5,
"size": "1280x720",
"content": [
{ "type": "input_text", "text": "参考图片中的产品、参考视频的镜头运动和参考音频的节奏，生成约 5 秒的产品视频" },
{ "type": "input_image", "image_url": "https://example.com/reference.png", "name": "reference.png" },
{ "type": "input_video", "video_url": "https://example.com/reference.mp4", "name": "reference.mp4" },
{ "type": "input_audio", "audio_url": "https://example.com/reference.mp3", "name": "reference.mp3" }
]
}'本地 PNG、MP4 和 MP3/WAV
本地文件先转换为 data URL，再放入同一个 content 数组。MP3 使用 audio/mpeg，WAV 使用 audio/wav。
import { readFile } from "node:fs/promises";
const apiKey = process.env.VIDEO_API_KEY;
if (!apiKey) throw new Error("请设置 VIDEO_API_KEY");
async function dataUrl(path, mimeType) {
const bytes = await readFile(path);
return `data:${mimeType};base64,${bytes.toString("base64")}`;
}
const prompt = "参考图片、视频和音频生成约 5 秒的视频";
const body = {
model: "YOUR_VIDEO_MODEL_ID",
prompt,
seconds: 5,
size: "1280x720",
content: [
{ type: "input_text", text: prompt },
{ type: "input_image", image_url: await dataUrl("./reference.png", "image/png"), name: "reference.png" },
{ type: "input_video", video_url: await dataUrl("./reference.mp4", "video/mp4"), name: "reference.mp4" },
{ type: "input_audio", audio_url: await dataUrl("./reference.mp3", "audio/mpeg"), name: "reference.mp3" }
]
};
const response = await fetch("/v1/videos", {
method: "POST",
headers: {
authorization: `Bearer ${apiKey}`,
"content-type": "application/json"
},
body: JSON.stringify(body)
});
const result = await response.json();
if (!response.ok) throw new Error(result?.error?.message || JSON.stringify(result));
console.log("task_id:", result.task_id || result.id);VIDEO_API_KEY="YOUR_API_KEY" node create-video.mjs附件文件名
推荐在每个媒体项中传入 name，与 type、image_url / video_url / audio_url 同层。公网 URL 和 Base64 data URL 都使用相同写法。该字段是本服务的扩展约定，不是 OpenAI Videos 的必填字段。
{
"type": "input_image",
"image_url": "https://example.com/character.png",
"name": "许清岚.png"
}| 传法 | 当前支持情况 |
|---|---|
content[].name | 推荐。保存并转发名称，任务详情显示该名称；图片、视频、音频均可携带，媒体类型仍取决于模型能力。 |
content[].filename、fileName、file_name | 字段会保留并转发，TRAE 接入可识别这些别名；当前任务详情仅按 name 展示。建议统一使用 name，不要同时传入互相冲突的名称。 |
images: [{url, name}] 或 images: [{data, name}] | 兼容图片数组；data 为完整 Base64 data URL。名称应使用 name，不要在该数组里改用 filename。 |
文件名请使用非空字符串，建议保留扩展名、不超过 120 个字符，同一任务内保持名称唯一。文件名只作为名称元数据，不是本机文件路径，也不会改变素材内容。不要把名称放进 image_url: {url, name} 等内层 URL 对象：当前接入会丢失该位置的名称。
不传名称仍可创建任务，但页面可能显示“素材 1”等默认名称，下游可能使用内部素材 ID。Base64 不携带原文件名，URL 中的文件名也不会自动提取为 name；只在提示词里写文件名不能补齐附件名称。
TRAE 的提示词引用
保存文件名不等于支持任意 @文件名 精确引用。当前 TRAE 已有 @图N、@图片N、@视频N 编号映射；需要明确引用时，推荐附件命名为 图1.png、图2.png，在提示词中使用 @图1、@图2。编号来自附件名称，不按提示词的出现顺序重新编号。
{
"model": "tr_seedance-2.0",
"prompt": "@图2 中的人物站在 @图1 的场景中",
"seconds": 5,
"content": [
{ "type": "input_image", "image_url": "https://example.com/scene.png", "name": "图1.png" },
{ "type": "input_image", "image_url": "https://example.com/character.png", "name": "图2.png" }
]
}例如 name: "许清岚.png" 可保留和展示名称，但当前尚未提供 @许清岚.png 到具体素材的专用映射。以上说明适用于本服务 JSON 接口，不表示支持 OpenAI 的 multipart input_reference 文件上传格式。
任务列表
/v1/videoscurl /v1/videos \
-H "Authorization: Bearer YOUR_API_KEY"查询任务
/v1/videos/{task_id}创建成功后保存返回的 id 或 task_id，再轮询查询接口。queued 或 in_progress 时继续轮询；completed 时读取 video_url；failed 时读取 error。
curl /v1/videos/YOUR_TASK_ID \
-H "Authorization: Bearer YOUR_API_KEY"OpenAI 兼容字段
图片使用 input_image.image_url，视频使用 input_video.video_url，音频使用 input_audio.audio_url。
| 字段 | 说明 |
|---|---|
model | 从 /v1/models 返回的可用视频模型 ID。 |
prompt | 视频生成提示词；也可在 content 中使用 input_text。建议不超过 20000 字符。 |
seconds | 期望视频时长。 |
size | 宽x高，例如 1280x720（横屏）、720x1280（竖屏）。TRAE 在未传 aspect_ratio 时按宽高转换画幅；仅支持 16:9、9:16、1:1。其他渠道的可用尺寸以所选模型为准。 |
aspect_ratio | 扩展字段，可用 16:9、9:16、1:1 指定 TRAE 画幅；优先于 size，也接受 aspectRatio。 |
resolution | 渠道扩展的分辨率档位，例如 720p、1080p；不表达横竖屏，也不保证成品像素尺寸。 |
duration | seconds 的兼容别名。 |
frame_mode | 可选画面模式；也可使用 frameMode。 |
content[].name | 可选附件文件名；建议传入原文件名。详见“附件文件名”中的传法和引用规则。 |
content | 可同时包含 input_text、input_image、input_video 和 input_audio。 |
不要提交上游内部字段，例如 vid、audioVid、reference_images、reference_videos、reference_audios 或 input_reference。
size 与横竖屏
以下为 TRAE 通道示例，使用小写字母 x 分隔宽、高。调用方传 size 即可，无需再传相同比例的 aspect_ratio。
| size | TRAE 画幅 |
|---|---|
1280x720 / 1920x1080 | 横屏 16:9 |
720x1280 / 1080x1920 | 竖屏 9:16 |
720x720 / 1080x1080 | 方形 1:1 |
TRAE 的优先级为：显式 aspect_ratio → size 宽高 → 提示词中的明确比例 → 默认 16:9。旧的 size: "720p" / "1080p" 没有画幅，也会从提示词提取 16:9、9:16、1:1，兼容全角冒号和空格。单独写 9:16 即可，无需带“画幅”；9:16、16:9 优先于 1:1，“唇型 1:1 精准同步”“1:1 还原”等不作为画幅。同一优先级出现多个比例时按提示词顺序取第一个，不因多个比例报错；单独的“横屏/竖屏”词语不用于推断。页面默认“自动（按提示词）”，选定画幅后才发送具体宽高。
未显式指定画幅时，1080:960 格式无效；1080x960 对应不支持的 9:8。TRAE 返回 size_invalid。视频中心已返回 202 的任务会在异步提交后显示该错误。该兼容转换只指定画幅，不进行缩放，也不保证成品为指定像素尺寸。
注意事项
- JSON 请求应明确设置
Content-Type: application/json。 - 不要手动构造发往上游的 multipart boundary；保持 OpenAI 兼容的 JSON
content输入即可。 - 本地文件转成 Base64 后体积约增加三分之一。单个素材不能超过 30 MB，单个任务素材总量不能超过 60 MB，最多可提交 12 个参考素材。
- 各模型允许的图片、视频、音频数量和时长不同，应以
/v1/models返回的能力为准。 - MP3 推荐使用
audio/mpeg，WAV 使用audio/wav。
取消任务
/v1/videos/{task_id}/cancel排队任务会直接从本地队列取消，不会提交到上游视频服务。
设置失败
/v1/videos/{task_id}/fail手动结束仍在排队或进行中的任务，停止本地后续状态查询并退回原扣款点数。该操作不会向上游伪造取消请求。
下载视频
/v1/videos/{task_id}/content