zh · Markdown
EVA 豆包原生视频 API:官转线路
Seedance 2.0、2.5 国内版与海外版原生协议、素材、任务和计费说明。
选分组线路
对于按分辨率分组的线路,请在模型广场选择分辨率、计费方式和线路。使用该线路的 API Key,并在请求中明确填写同一个模型 ID 和匹配的分辨率,例如 720p。
适用于 EVA「官转」分组的 Seedance 2.0、2.0 Fast、2.0 Mini 和 2.5 国内版、海外版。任务 ID、素材地址和用量为示例值。运行创建示例会提交一条计费任务。
调用前先确认模型 ID 和线路。本文适用于国内版或海外版的按 Token 线路。
1. 接口与鉴权
网关地址为 https://api.eveapis.com。使用 EVA 控制台创建「官转」分组的 API Key,在所有 EVA API 请求中传入 Authorization: Bearer <EVA_API_KEY>。生成请求另需 Content-Type: application/json。
| 操作 | 方法 | 路径 |
|---|---|---|
| 创建视频任务 | POST |
/doubao/api/v3/contents/generations/tasks |
| 查询单条视频任务 | GET |
/doubao/api/v3/contents/generations/tasks/{id} |
| 下载视频 | GET |
查询响应中的 content.video_url |
创建成功后保存 EVA 返回的 id,用同一个 Key 查询。原生接口请直接填写下表中的 EVA 模型 ID。若客户端自动加载的模型列表为空,仍可手动填入对应 ID,线路与人民币报价可在模型广场查看。模型广场
| 型号 | 国内版模型 ID | 海外版模型 ID | 线路分辨率 | 输出时长 |
|---|---|---|---|---|
| Seedance 2.0 | seedance-2-0-cn-token-720p-1080p |
seedance-2-0-token-720p-1080p |
720p、1080p |
4–15 秒 |
| Seedance 2.0 Fast | seedance-2-0-fast-cn-token-720p |
seedance-2-0-fast-token-720p |
720p |
4–15 秒 |
| Seedance 2.0 Mini | seedance-2-0-mini-cn-token-720p |
seedance-2-0-mini-token-720p |
720p |
4–15 秒 |
| Seedance 2.5 | seedance-2-5-cn-token-720p-1080p |
seedance-2-5-token-720p-1080p |
720p、1080p |
4–30 秒 |
2. 上传本地图片、视频和音频
先把文件上传到你的对象存储或文件服务器,再将每个文件的 HTTPS 下载链接填进生成请求。已经有可用 HTTPS 链接的素材可以直接引用。下载链接应能被服务端直接 GET,有效期覆盖任务排队和处理时间。私有文件可使用带有效期的签名下载链接。
如果你的存储签发了允许 PUT 的上传链接,可以按以下方式上传文件。*_PUT_URL 是存储提供的上传地址,*_GET_URL 是上传后用于下载的地址。签名绑定了 Content-Type 等请求头时,上传必须使用签名所要求的值。
curl --fail-with-body --upload-file ./reference.png \
-H 'Content-Type: image/png' "$IMAGE_PUT_URL"
curl --fail-with-body --upload-file ./motion.mp4 \
-H 'Content-Type: video/mp4' "$VIDEO_PUT_URL"
curl --fail-with-body --upload-file ./sound.mp3 \
-H 'Content-Type: audio/mpeg' "$AUDIO_PUT_URL"
上传后,用对应的 *_GET_URL 替换下文 JSON 中的素材地址。存储请求使用存储服务签发的凭据。EVA Key 用于向 EVA 创建和查询任务。
豆包原生接口从 content[].image_url.url、content[].video_url.url、content[].audio_url.url 读取素材。已有 HTTPS 下载链接可直接填写;本地文件也可以按下面的方法先上传到 EVA,再把完成上传返回的 url 填入原生请求。
通过 EVA 上传本地图片、视频和音频
EVA 分片上传接口支持 JPEG、PNG、WebP 图片(单张最大 20 MiB)、MP4、MOV 视频(单个最大 64 MiB)和 MP3、WAV 音频(单个最大 15 MiB)。分片大小以返回的 chunk_size 为准,当前为 8 MiB;按索引从 0 开始上传。完成上传后使用返回的 url 作为素材下载链接。临时链接有有效期,请在任务处理期间保持可访问。
将以下代码保存为 upload_reference.py,安装 requests 并设置 EVA_API_KEY:
import hashlib
import mimetypes
import os
import pathlib
import sys
import requests
base = 'https://api.eveapis.com'
path = pathlib.Path(sys.argv[1])
kind = sys.argv[2] # image、video 或 audio
mime = mimetypes.guess_type(path.name)[0]
allowed = {
'image': ('image/jpeg', 'image/png', 'image/webp'),
'video': ('video/mp4', 'video/quicktime'),
'audio': ('audio/mpeg', 'audio/wav', 'audio/x-wav'),
}
if kind not in allowed or mime not in allowed[kind]:
raise ValueError('文件类型与素材类型不匹配')
raw = path.read_bytes()
s = requests.Session()
s.headers.update({'Authorization': 'Bearer ' + os.environ['EVA_API_KEY']})
def checked(response):
response.raise_for_status()
return response
created = checked(s.post(base + '/v1/video/uploads', json={
'name': path.name, 'media_type': kind, 'mime_type': mime,
'size': len(raw), 'sha256': hashlib.sha256(raw).hexdigest(),
}, timeout=60)).json()
uid, chunk_size = created['upload']['id'], created['chunk_size']
for index, offset in enumerate(range(0, len(raw), chunk_size)):
chunk = raw[offset:offset + chunk_size]
checked(s.put(base + '/v1/video/uploads/' + uid + '/chunks/' + str(index),
headers={'Content-Type': 'application/octet-stream',
'X-Chunk-SHA256': hashlib.sha256(chunk).hexdigest()},
data=chunk, timeout=120))
completed = checked(s.post(base + '/v1/video/uploads/' + uid + '/complete', timeout=60)).json()
print('素材 URL:', completed['url'])
python upload_reference.py reference.png image
python upload_reference.py motion.mp4 video
python upload_reference.py sound.mp3 audio
分别将输出的 URL 放入对应的 image_url.url、video_url.url、audio_url.url。上传文件使用 EVA 存储上限;模型生成仍须满足下方原生协议的素材规格。
素材规格
| 素材 | 常用格式 | 单文件规格 |
|---|---|---|
| 图片 | JPEG、PNG、WebP、BMP | 小于 30 MB。宽、高各 300–6000 像素,宽高比 0.4–2.5 |
| 视频 | MP4、MOV | 不超过 200 MB。24–60 FPS,宽、高各 300–6000 像素,宽高比 0.4–2.5,总像素 407,696–8,295,044 |
| 音频 | MP3、WAV | 不超过 15 MB |
| 全模态参考限制 | Seedance 2.0 系列 | Seedance 2.5 |
|---|---|---|
| 图片数量 | 最多 9 张 | 最多 30 张 |
| 视频数量 | 最多 3 段 | 最多 10 段 |
| 音频数量 | 最多 3 段 | 最多 10 段 |
| 单段参考视频、音频时长 | 2–15 秒 | 2–30 秒,视频编辑的参考视频为 4–30 秒 |
| 参考视频总时长、参考音频总时长 | 两类分别不超过 15 秒 | 两类分别不超过 30 秒 |
| 仅使用音频作为参考 | 需再提供至少一张图片或一段视频 | 可以只提供音频 |
以上为原生协议的素材规格。图片与音频也可按原生协议提供 data:image/png;base64,...、data:audio/wav;base64,... 等 Data URL。批量或大文件请使用 HTTPS 链接,避免 Base64 撑大 JSON 请求。 豆包原生参数规范
3. 创建视频任务
POST /doubao/api/v3/contents/generations/tasks
| 顶层字段 | 类型 | 说明 |
|---|---|---|
model |
string | 必填。使用第 1 节的 EVA 模型 ID |
content |
array | 必填。按下表组织提示词和素材,每项独立填写 |
duration |
integer | 输出秒数。使用模型表中的时长,或填写 -1 由模型选择 |
resolution |
string | 线路支持的 720p 或 1080p,建议显式填写 |
ratio |
string | 如 16:9、9:16、1:1、4:3、3:4、21:9 或 adaptive |
generate_audio |
boolean | true 输出有声视频,false 输出无声视频。和参考音频是两个独立选项 |
watermark |
boolean | 控制输出视频是否带水印 |
return_last_frame |
boolean | 设为 true 时,可在完成响应中读取尾帧地址 content.last_frame_url |
任务状态通过查询接口获取。创建请求中省略 callback_url。
content[].type |
数据字段 | role |
|---|---|---|
text |
text,字符串提示词 |
省略 |
image_url |
image_url.url |
reference_image、first_frame 或 last_frame |
video_url |
video_url.url |
reference_video |
audio_url |
audio_url.url |
reference_audio |
图片、视频、音频混合参考
将下面内容保存为 request.json。每张图、每段视频和每段音频都在 content 中占一项。替换素材地址后执行创建命令一次。
{
"model": "seedance-2-5-cn-token-720p-1080p",
"content": [
{"type": "text", "text": "参考图片中的产品外观、视频的运镜和音频的节奏,生成一段产品展示视频。"},
{"type": "image_url", "role": "reference_image", "image_url": {"url": "https://media.example.com/reference.png"}},
{"type": "video_url", "role": "reference_video", "video_url": {"url": "https://media.example.com/motion.mp4"}},
{"type": "audio_url", "role": "reference_audio", "audio_url": {"url": "https://media.example.com/sound.mp3"}}
],
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": true,
"watermark": false,
"return_last_frame": true
}
curl --fail-with-body 'https://api.eveapis.com/doubao/api/v3/contents/generations/tasks' \
-H "Authorization: Bearer $EVA_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @request.json
创建成功返回 HTTP 200。保存响应中的 id。最小响应示例:
{"id": "task_example_123"}
文生视频、首尾帧和单独参考音频
文生视频只需要模型 ID 和文本,建议明确指定分辨率和时长。将以下内容保存为 request.json,沿用上面的创建命令。
{
"model": "seedance-2-0-cn-token-720p-1080p",
"content": [{"type": "text", "text": "黄昏湖畔,镜头缓慢向前推进,画面平稳。"}],
"resolution": "720p",
"ratio": "16:9",
"duration": 5
}
- 首帧图生视频使用一张标记为
first_frame的图,可配合提示词。首尾帧场景使用一张first_frame和一张last_frame。同一次提交选择首帧、首尾帧或全模态参考其中一种方式。 - 仅参考音频时选择 Seedance 2.5,
content放入role: reference_audio的音频项,可配合提示词。generate_audio按是否需要有声输出设置。
首尾帧请求的 content 示例
[
{"type": "text", "text": "镜头从产品全景平滑过渡到细节特写。"},
{"type": "image_url", "role": "first_frame", "image_url": {"url": "https://media.example.com/first.png"}},
{"type": "image_url", "role": "last_frame", "image_url": {"url": "https://media.example.com/last.png"}}
]
4. 查询任务与下载视频
GET /doubao/api/v3/contents/generations/tasks/{id}
curl --fail-with-body "https://api.eveapis.com/doubao/api/v3/contents/generations/tasks/${EVA_TASK_ID}" \
-H "Authorization: Bearer $EVA_API_KEY"
完成响应示例。id 为 EVA 任务 ID。其他原生字段按任务的实际响应返回,程序应允许字段缺失。
{
"id": "task_example_123",
"status": "succeeded",
"content": {
"video_url": "https://media.example.com/generated-video.mp4",
"last_frame_url": "https://media.example.com/generated-last-frame.jpeg"
},
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"usage": {"completion_tokens": 100000, "total_tokens": 100000}
}
status |
处理方式 |
|---|---|
queued、running |
等待后继续查询 |
succeeded |
读取 content.video_url 并下载,按需保存尾帧和用量 |
failed、expired、cancelled |
停止轮询。存在 error 时读取 error.code 和 error.message |
可以每 5 秒查询一次,并设置本地总等待时限。达到时限后保留 id,之后可继续查询。视频地址可能带有效期,完成后及时下载。下载响应中的签名链接时,使用链接本身的授权。
curl --fail-with-body --location "$VIDEO_URL" --output result.mp4
国内版和海外版的原生线路按 Token 计费。每百万 Token 的人民币单价按模型、线路以及是否有参考视频确定。响应包含 usage 时,可保留 usage.completion_tokens、usage.total_tokens 和 EVA 任务 ID 用于对账,最终金额以用量账单为准。模型广场与价格 · 原生查询字段
5. 常见错误与重试
| HTTP 状态 | 处理方式 |
|---|---|
400 |
核对 JSON、模型 ID、content 结构、素材地址和模型限制 |
401 |
检查 EVA Key 是否正确、启用、有效 |
403 |
检查 Key 分组、模型权限或任务访问权限 |
404 |
核对路径、任务 ID 和当前账号。只查询自己的任务 |
429 |
查询可按 Retry-After 退避。创建发生错误时先核查任务是否已受理 |
503 |
核对 Key 分组、模型 ID 和对应线路的可用状态。若已拿到任务 ID,继续查询原任务 |
5xx 或网络超时 |
查询可稍后重试。创建结果不明时,保存请求时间和响应信息,核查后再决定是否重新提交 |
6. Python 示例
安装 requests,设置环境变量 EVA_API_KEY。先按第 2 节上传素材,将下载链接填入 request.json。下面的脚本提交一次,保存任务 ID,轮询最多 10 分钟并下载视频。
import json
import os
import time
from pathlib import Path
from urllib.parse import quote
import requests
tasks = "https://api.eveapis.com/doubao/api/v3/contents/generations/tasks"
headers = {"Authorization": f"Bearer {os.environ['EVA_API_KEY']}"}
payload = json.loads(Path("request.json").read_text(encoding="utf-8"))
created = requests.post(tasks, headers=headers, json=payload, timeout=45)
created.raise_for_status()
task_id = created.json()["id"]
Path("eva-task-id.txt").write_text(task_id + "\n", encoding="utf-8")
print(f"EVA 任务 ID: {task_id}")
task_url = f"{tasks}/{quote(task_id, safe='')}"
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
delay = 5
try:
reply = requests.get(task_url, headers=headers, timeout=15)
except (requests.Timeout, requests.ConnectionError):
pass
else:
if reply.status_code == 429:
retry_after = reply.headers.get("Retry-After", "")
if retry_after.isdecimal():
delay = max(delay, int(retry_after))
elif not 500 <= reply.status_code < 600:
reply.raise_for_status()
result = reply.json()
status = result["status"]
if status == "succeeded":
with requests.get(result["content"]["video_url"], stream=True, timeout=60) as video:
video.raise_for_status()
with Path("result.mp4").open("wb") as output:
for chunk in video.iter_content(chunk_size=1024 * 1024):
output.write(chunk)
break
if status in {"failed", "expired", "cancelled"}:
raise RuntimeError(f"任务 {task_id} 状态为 {status}: {result.get('error', {})}")
time.sleep(min(delay, max(0, deadline - time.monotonic())))
else:
raise TimeoutError(f"等待超时,可使用任务 ID {task_id} 继续查询")