eva
← 开发者文档

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} 继续查询")

查看按次与按秒视频接口