NezhaGateNezhaGate
seedance-2.5-token

Seedance 2.5 · Token · API

POST https://nezhagate.com/v1/videos/generations

按实际视频 Token 计费的异步视频。样片和升级是两笔订单;参考视频也计入用量。请保存并查询返回的网关任务号,客户端超时不要再次提交购买。 仍需内容审核;不提供无审核模式。 按BytePlus海外公开美元标价约95折定价,四舍五入保留一位小数。 MP4适合一般使用;MOV可能需要下载后用兼容播放器打开。

在 Playground 试用 →

直接生成正式片,或先查看草稿再升级至1080p。先选择用途,再查看对应参数与调用示例。

你想完成什么?

直接生成正式片

当前步骤所需参数
参数类型说明
model必填string
prompt可选string提示词;与 content 二选一。升级样片时不传。
content可选arraytext/image_url/video_url/audio_url 内容块,参考素材使用 HTTPS URL;最多30图、10视频、10音频。不接受供应商素材ID。
duration可选integer4–30秒,默认5秒;升级不传。
resolution可选string
ratio可选stringadaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
output_format可选stringmp4 / mov. MP4适合一般使用;MOV可能需要下载后用兼容播放器打开。
进阶:使用标准型号生成草稿

使用 seedance-2.5-token 时,传 draft: true,并明确指定 resolution: 480p。未启用 draft 的普通480p任务不能升级。

请求示例

认证
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

在控制台创建 API Key 后即可调用。

cURL · POST /v1/videos/generations

响应示例

202 · JSON
完整调用示例 · 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,再运行一次下方脚本。脚本会自动完成草稿、轮询及升级;草稿和正式片分别计费。不要重复运行整个脚本来查询已有任务。

Python 3 · 480p → 1080p
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 · 人物与参考素材
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 · GET /v1/videos/jobs/{id}
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事件。
200 · JSON
{
  "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 判断。下表是最常见的几种,完整列表见 错误码。

HTTPcode说明
401invalid_api_key没带 Key,或 Key 无效、已停用(missing_api_key、invalid_api_key)。
402insufficient_quota余额不足,或这把 Key 达到了预算上限(insufficient_quota)。
400invalid_request参数有误或模型不存在(如 model_not_found),error.param 指出是哪个字段。
—content_policy内容审核未通过:提示词、参考素材,或生成的画面 / 声音被判违规。未计费;原样重交还会被拒,请改写提示词或更换素材。视频任务在 status 为 failed 时的 error 里返回。
429rate_limit_exceeded超过了这把 Key 设置的每分钟请求数或免费模型的每日额度,或者这个模型的所有线路都已满载(rate_limit_exceeded)。有 Retry-After 头就按它等待,没有就等几秒再试。
502upstream_*上游出错或超时,自动换线后仍然失败;code 写明原因,如 upstream_timeout、upstream_unavailable。没有计费,可以重试。

完整错误码列表 →