按实际视频 Token 计费的异步视频。样片和升级是两笔订单;参考视频也计入用量。请保存并查询返回的网关任务号,客户端超时不要再次提交购买。 仍需内容审核;不提供无审核模式。 按BytePlus海外公开美元标价约95折定价,四舍五入保留一位小数。 MP4适合一般使用;MOV可能需要下载后用兼容播放器打开。
在 Playground 试用 →直接生成正式片,或先查看草稿再升级至1080p。先选择用途,再查看对应参数与调用示例。
你想完成什么?
直接生成正式片
当前步骤所需参数继承草稿的提示词、参考素材与时长,不要重新传入这些字段。
| 参数 | 类型 | 说明 |
|---|---|---|
| model必填 | string | |
| prompt可选 | string | 提示词;与 content 二选一。升级样片时不传。 |
| content可选 | array | text/image_url/video_url/audio_url 内容块,参考素材使用 HTTPS URL;最多30图、10视频、10音频。不接受供应商素材ID。 |
| duration可选 | integer | 4–30秒,默认5秒;升级不传。 |
| resolution可选 | string | |
| ratio可选 | string | adaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 |
| output_format可选 | string | mp4 / mov. MP4适合一般使用;MOV可能需要下载后用兼容播放器打开。 |
| draft_task_id必填 | string | 本账户已成功的 Token 草稿网关任务号。不支持按秒计费任务、普通480p正式片或外部任务号。 |
进阶:使用标准型号生成草稿
使用 seedance-2.5-token 时,传 draft: true,并明确指定 resolution: 480p。未启用 draft 的普通480p任务不能升级。
请求示例
认证
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
在控制台创建 API Key 后即可调用。
响应示例
完整调用示例 · Python 3 · 480p → 1080p
草稿 → 1080p
仅支持当前账户已完成的 Token 草稿。按秒计费版本、普通480p正式片及外部任务号均不能用于升级。
先生成480p草稿,轮询至 succeeded,再把 NezhaGate 任务号作为 draft_task_id 交给 Token 正式片模型。模型根据原草稿任务生成1080p正式片,不是任意MP4文件的放大工具。不要重复传 prompt、content、duration、ratio、seed 或 generate_audio。草稿与正式片分别计费。
Python 3(无需额外安装依赖)。先设置环境变量 NEZHAGATE_API_KEY,再运行一次下方脚本。脚本会自动完成草稿、轮询及升级;草稿和正式片分别计费。不要重复运行整个脚本来查询已有任务。
import json
import os
import time
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen
BASE_URL = "https://nezhagate.com"
API_KEY = os.environ["NEZHAGATE_API_KEY"]
def request(path, payload=None):
data = json.dumps(payload).encode() if payload is not None else None
req = Request(BASE_URL + path, data=data, headers={
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json",
})
with urlopen(req, timeout=60) as response:
return json.load(response)
def submit(payload):
# Do not automatically retry a POST: its outcome may be unknown.
job = request("/v1/videos/generations", payload)
job_id = job["id"]
print("Submitted:", job_id, flush=True)
return job_id
def wait_for(job_id):
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
try:
job = request("/v1/videos/jobs/" + job_id)
except HTTPError as exc:
if exc.code != 429 and exc.code < 500:
raise
time.sleep(10)
continue
except (URLError, TimeoutError):
time.sleep(10)
continue
progress = job.get("progress", {})
print(job_id, job["status"], progress.get("phase", ""), flush=True)
if job["status"] == "succeeded":
return job
if job["status"] == "failed":
raise RuntimeError(json.dumps(job.get("error"), ensure_ascii=False))
time.sleep(5)
raise TimeoutError("Keep polling this job; do not resubmit: " + job_id)
if __name__ == "__main__":
# Two separately billed tasks. Save the printed IDs to resume polling.
draft_id = submit({
"model": "seedance-2.5-token-draft",
"prompt": "A sunrise over the sea",
"duration": 5,
"resolution": "480p",
})
draft = wait_for(draft_id)
print("Draft video:", draft["data"][0]["url"])
final_id = submit({
"model": "seedance-2.5-token",
"draft_task_id": draft_id,
"resolution": "1080p",
})
final = wait_for(final_id)
print("Final video:", final["data"][0]["url"])
人物与参考素材
API调用:先将本地文件上传到可公开访问的HTTPS存储,再通过 content 传入 image_url、video_url 或 audio_url。任务运行期间保持链接可访问。NezhaGate 自动将参考素材导入素材库,等全部素材为 Active 后才提交生成;真人参考也必须经过此步骤,文件上传成功不等于素材已就绪。调用方无需另调素材库接口。
上传文件后可自由选择与增删。点击 Run 并确认、余额冻结成功后,才进行素材入库与审核。
| 步骤 | 说明 |
|---|---|
| 1. 上传文件 | 将人物图片上传到可公开访问的 HTTPS 存储;JSON 不接收本地路径或文件二进制。 |
| 2. 提交引用 | 在 content 中传 image_url,提示词用 @Image1 引用人物。 |
| 3. 入库与审核 | NezhaGate 自动入库并等待审核;调用方不需要创建素材组或传 asset:// ID。 |
| 4. 查看结果 | 轮询同一任务的 progress;素材未通过则返回 failed 和 error,不提交视频生成。 |
- 最多30张图、10段视频、10段音频,合计50项。参考视频合计不超过30秒,参考音频合计不超过30秒。网页上传限制:图片<30MB、视频50MB、音频15MB。API JSON接收HTTPS链接,不接收本地路径或文件二进制。 保留高清原图,单张小于30MB;宽高各301–5999像素,宽高比0.4–2.5。真人参考须完成素材准备后使用。 MP4适合一般使用;MOV可能需要下载后用兼容播放器打开。
data[0].source_url— 原始链接由视频服务返回,可能过期,请及时保存;也可下载本站保留的原片。
curl https://nezhagate.com/v1/videos/generations \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "seedance-2.5-token",
"content": [
{
"type": "text",
"text": "The character from @Image1 walks by the sea."
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/reference.jpg"
}
}
],
"duration": 5,
"resolution": "720p"
}'任务状态轮询
使用相同的 Bearer API Key,每3–5秒轮询 GET /v1/videos/jobs/{id},仅任务所属账户可查询。保持原 status 逻辑:queued / processing 继续轮询;succeeded 读取 data[0].url;failed 读取 error。progress 是 Token 任务新增字段,客户端需兼容字段缺失与未来新增阶段。
curl https://nezhagate.com/v1/videos/jobs/img_example -H 'Authorization: Bearer YOUR_API_KEY'
| progress.phase | 说明 |
|---|---|
| queued | 等待任务处理 |
| preparing | 准备参考素材 |
| reviewing | 审核参考素材 |
| submitting | 提交生成请求 |
| provider_queued | 等待生成 |
| generating | 生成视频中 |
| delivering | 保存视频结果 |
| succeeded | 已完成 |
| material_failed | 素材未通过或导入失败 |
| submission_failed | 生成请求提交失败或未确认 |
| generation_failed | 视频生成失败 |
| delivery_failed | 保存结果失败 |
| failed | 任务失败 |
- phase 是机器可读阶段,不是百分比或耗时预估。ready / total 表示本任务去重后已就绪 / 所需参考素材数;纯文本和草稿升级可以为0。API 的 label、detail 是英文展示文案,不作为程序判断依据。terminal 对应顶层终态;failed_stage 未失败时为null,失败时为失败阶段。恢复处理可能跳过或重复部分阶段。
- submitted 仅在确认生成任务号后为true;false表示尚未开始提交;null表示已发起提交但结果未确认。null或超时均不能自动重提。reservation_released 仅在确认零费用结算释放后为true;false不代表已扣费。updated_at 是任务记录更新时间,并非独立的阶段时间;job_id 是NezhaGate任务号。
- 参数、余额或提示词初审拒绝时,在创建任务前返回HTTP错误,没有可轮询的任务号。初审通过不保证最终审核通过。素材入库或审核失败会停止生成,通过failed和error反馈。暂时的轮询或网络错误请退避后查询同一任务,不要重复生成。本次不新增中间阶段Webhook事件。
{
"id": "img_example",
"object": "video.generation.job",
"status": "processing",
"created": 1792800000,
"model": "seedance-2.5-token",
"progress": {
"phase": "reviewing",
"label": "Reviewing references",
"detail": "References ready: 3 / 5",
"ready": 3,
"total": 5,
"terminal": false,
"failed_stage": null,
"submitted": false,
"reservation_released": false,
"updated_at": "2026-10-24T05:00:00+00:00",
"job_id": "img_example"
}
}内容要求
Seedance 的每个任务都要经过内容审核,范围包括提示词、参考素材和生成的成片,画面和声音都审。没通过审核的任务以 content_policy 失败,不收费。
什么时候审
提交时先审提示词和参考素材,成片生成后再审一次画面和声音。所以被拒的结果可能在提交后几秒内返回,也可能要等到渲染结束,半小时以上才返回。任务以 status 为 failed、error.code 为 content_policy 结束,就是没通过审核;用 Webhook 会收到 video.failed 事件。
不收费
被拒的任务不扣费:提交时预扣的金额在任务结束时全额退回,调用日志里也显示未计费。
声音
成片的声音(对白、旁白、歌声和音效)由模型按提示词生成,和画面一起审核:提示词里写的台词、旁白和歌词会被念出来或唱出来。不需要人声的片子,提示词里就别写台词和歌词。声音没通过时,error.param 为 audio,message 会写明是生成的声音还是上传的参考音频。
常被拒的内容
- 色情、裸露或性暗示,包括 AI 生成或合成的画面
- 血腥、残忍、自残,以及中枪、流血等暴力伤害
- 枪支、爆炸物、毒品
- 涉及未成年人的性化内容一律不行;未成年人和烟酒、毒品或危险行为同框也会被拒
- 政治人物、明星、体育和商界名人等公众人物的形象或声音,包括长得很像的人物
- 受版权保护的角色和 IP 形象,例如迪士尼、漫威角色
- 仇恨、歧视内容和虚假新闻
长分镜脚本
一条成片只要有一个镜头违规,整条都会被拒,长分镜脚本最容易踩到:动作戏里的枪战和流血特写、未成年人出现在饮酒或吸烟的场景里,都会让整条失败。提交前通读一遍,删掉或改写这类镜头。
真人肖像
用真人照片作参考,需要你有权使用其肖像;各型号能否用真人参考图,见本页上方的说明。
被拒之后
原样重新提交还会被拒。先找出可能违规的那部分,改写提示词或更换参考素材,再重新提交。
错误码: content_policy · status: failed
错误码
错误都是 error.message / error.type / error.code / error.param 这个结构,请按 code 判断。下表是最常见的几种,完整列表见 错误码。
| HTTP | code | 说明 |
|---|---|---|
| 401 | invalid_api_key | 没带 Key,或 Key 无效、已停用(missing_api_key、invalid_api_key)。 |
| 402 | insufficient_quota | 余额不足,或这把 Key 达到了预算上限(insufficient_quota)。 |
| 400 | invalid_request | 参数有误或模型不存在(如 model_not_found),error.param 指出是哪个字段。 |
| — | content_policy | 内容审核未通过:提示词、参考素材,或生成的画面 / 声音被判违规。未计费;原样重交还会被拒,请改写提示词或更换素材。视频任务在 status 为 failed 时的 error 里返回。 |
| 429 | rate_limit_exceeded | 超过了这把 Key 设置的每分钟请求数或免费模型的每日额度,或者这个模型的所有线路都已满载(rate_limit_exceeded)。有 Retry-After 头就按它等待,没有就等几秒再试。 |
| 502 | upstream_* | 上游出错或超时,自动换线后仍然失败;code 写明原因,如 upstream_timeout、upstream_unavailable。没有计费,可以重试。 |