视频

文生视频与图生视频，提供国内和海外渠道。使用同一接口地址和已开通视频权限的 API Key，在请求中选择渠道。

接口地址

也支持 x-api-key，与文本接口保持一致。

国内与海外渠道

海外渠道支持 NSFW。测试海外渠道时，请在创建请求中明确设置 "channel": "overseas"。继续使用已有的 API Key，不需要额外的 NSFW 参数。

不传 channel 时默认国内。两条渠道使用相同的模型 ID、接口地址、Key 和固定美元价目表。查询任务时无需再次传渠道，以任务响应中的 channel 为准。

渠道不可用时不会自动切换。缺少所选模型的海外配置或适用价格时，创建前返回 409 pricing_unavailable。不同渠道的测试请使用不同的 Idempotency-Key。

模型

不传 model 时默认使用 doubao-seedance-2-0-fast-260128。 4k 仅 doubao-seedance-2-0-260128 支持。 duration: -1 表示由模型自行决定时长。

创建任务

将已有 Key 放入环境变量 NIGHTFERRY_KEY。以下示例均使用 Mini、480p、4 秒、无音频，便于核对请求和费用。每次新测试换一个幂等键；重试同一任务时保留原值。

国内

curl -X POST https://api.nightferry.io/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NIGHTFERRY_KEY" \
  -H "Idempotency-Key: video-domestic-text-001" \
  -d '{
  "model": "doubao-seedance-2-0-mini-260615",
  "channel": "domestic",
  "content": [
    {
      "type": "text",
      "text": "a cat running through long grass, cinematic"
    }
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 4,
  "generate_audio": false
}'

海外

curl -X POST https://api.nightferry.io/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NIGHTFERRY_KEY" \
  -H "Idempotency-Key: video-overseas-text-001" \
  -d '{
  "model": "doubao-seedance-2-0-mini-260615",
  "channel": "overseas",
  "content": [
    {
      "type": "text",
      "text": "a cat running through long grass, cinematic"
    }
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 4,
  "generate_audio": false
}'

创建成功会先返回任务 ID，并不表示视频已经生成。以下为海外任务的受理响应示例：

{
  "id": "cgt-4f9a72b7476bc7838a470c3df57258da",
  "model": "doubao-seedance-2-0-mini-260615",
  "status": "queued",
  "channel": "overseas",
  "billing": {
    "currency": "USD",
    "state": "held",
    "charge_usd": null,
    "billable_tokens": null,
    "backfilled": false
  }
}

content 支持 text、image_url、 video_url、audio_url 四种元素，每个可选带 role：first_frame、last_frame、 reference_image、reference_video、 reference_audio。 content 中至少要有一项 text、image_url 或 video_url——只传音频会被拒绝。

其余可传字段：ratio、duration、 generate_audio、watermark、seed、 tools、safety_identifier、bitrate_mode、 output_format、omni_reference_task_type、 moderation_options.ips。

使用参考图

将示例中的图片地址替换为服务可读取的 HTTPS 图片地址。reference_image 表示参考图；如果需要固定首帧，使用 first_frame。

curl -X POST https://api.nightferry.io/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NIGHTFERRY_KEY" \
  -H "Idempotency-Key: video-overseas-image-001" \
  -d '{
  "model": "doubao-seedance-2-0-mini-260615",
  "channel": "overseas",
  "content": [
    {
      "type": "text",
      "text": "a cat running through long grass, cinematic"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/reference.jpg"
      },
      "role": "reference_image"
    }
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 4,
  "generate_audio": false
}'

与方舟的差异

• execution_expires_after 上限为 3600 秒。 传更大的值会被静默下调到该上限；小于 3600 会被拒绝，而不是上调——上调等于给了你没有请求过的更长窗口。
• 不支持 return_last_frame。直接拒绝而非忽略，因为我们无法把尾帧交付给你。
• 不支持 super_resolution_config。直接拒绝而非忽略。
• moderation_options 只接受 ips。 ip_mode 会被拒绝。
• 接受但会被丢弃，因为方舟客户端常会带上它们： callback_url、service_tier、draft、 priority、frames、camera_fixed，以及 content[].type=draft_task。

避免为同一个视频付两次钱

请带上 Idempotency-Key 请求头。携带相同 key 的重复请求会返回原任务，而不会再创建一个；改用另一渠道会返回 409 idempotency_conflict。其他参数的修改不会更新原任务，新测试应使用新 key。 如需用相同提示词重新生成，请使用不同的 Idempotency-Key；不同 key 不会按请求内容合并。

两个携带相同 key 的请求同时到达时，会在任何一个扣费之前就分出胜负：一个胜出，另一个被告知。 若胜出的那个尚未登记完成，落败方会收到 409 conflict——去轮询你已有的那个任务，或稍后重试。

即使不带该请求头，我们仍会在短时间窗口内识别同一密钥发出的规范化后相同的重复请求。但请使用该请求头，它是精确的。

查询任务

curl https://api.nightferry.io/api/v3/contents/generations/tasks/cgt-4f9a72b7476bc7838a470c3df57258da \
  -H "Authorization: Bearer $NIGHTFERRY_KEY"

把 URL 中的 ID 替换为创建响应中的 id，轮询间隔不要短于 5 秒。HTTP 200 只表示查询成功；请继续检查任务的 status。queued 和 running 表示仍需等待，succeeded 表示视频已交付，failed 表示任务失败。

生成成功并已扣费

{
  "id": "cgt-4f9a72b7476bc7838a470c3df57258da",
  "model": "doubao-seedance-2-0-mini-260615",
  "status": "succeeded",
  "channel": "overseas",
  "billing": {
    "currency": "USD",
    "state": "settled",
    "charge_usd": "0.137303",
    "billable_tokens": 40594,
    "backfilled": false
  },
  "content": {
    "video_url": "https://api.nightferry.io/v1/videos/cgt-4f9a72b7476bc7838a470c3df57258da.mp4"
  },
  "resolution": "480p",
  "duration": 4,
  "usage": {
    "completion_tokens": 40594,
    "total_tokens": 40594
  }
}

任务已受理，但生成失败

以下查询响应的 HTTP 状态仍是 200。通过 status: failed 和 error 判断失败；billing.state: released 表示占款已释放，不收本次生成费用。客户错误码不会细分具体审核阶段。

{
  "id": "cgt-4f9a72b7476bc7838a470c3df57258da",
  "model": "doubao-seedance-2-0-mini-260615",
  "status": "failed",
  "channel": "overseas",
  "billing": {
    "currency": "USD",
    "state": "released",
    "charge_usd": null,
    "billable_tokens": null,
    "backfilled": false
  },
  "error": {
    "code": "content_policy_violation",
    "message": "The request or its output did not pass content safety checks."
  }
}

usage 中没有输入 token

completion_tokens 与 total_tokens 都是输出侧的计数。 视频接口没有 prompt 或输入 token 计数。两者通常相等，但并不保证相等，所以两个都会返回。

成片

content.video_url 在我们自己的域名下，且不需要 API 密钥—— 它就是用来直接交给浏览器或播放器的。请把这个 URL 本身当作凭证：任何拿到它的人都能观看， 所以不要把它发布到你不会发布该视频的地方。

我们保留 7 天。之后该 URL 返回 410。需要长期保存的请及时下载。

视频生成记录

API 和视频实验室创建的新任务默认保存原始提示词与生成参数，从任务创建起保留 30 天。生成失败的任务也保留输入。重试不会替换原记录或延长保留期限。

curl https://api.nightferry.io/api/v3/contents/generations/tasks/cgt-4f9a72b7476bc7838a470c3df57258da/record \
  -H "Authorization: Bearer $NIGHTFERRY_KEY"

使用任务所属租户的任意有效且未停用的 Key。响应包含任务字段、created_at 和 inputs。普通创建和状态查询响应不会附带保存的输入正文。

只有 available 记录包含上述四个内容字段。满 30 天后，记录查询和提示词搜索不再返回这些内容，保存的正文会被清理；任务与账单信息继续保留。创建时未保存输入的旧任务返回 never_captured，无法补回提示词。

在控制台的视频账单中点击任务 ID，即可打开详情；也可输入任务 ID 查找，或搜索保留期内的提示词。搜索支持中英文片段，不区分大小写，不使用通配符，最多输入 500 个字符。详情支持复制提示词和参数。控制台历史记录属于当前登录的租户，无需找回创建任务时的 Key。

生成的视频仍单独保留 7 天，详情页可在有效期内播放，并区分视频过期和播放错误。视频过期后，提示词可在其剩余期限内继续查看。参考文件仍是用完即清理的输入，历史记录不保存这些文件，也不提供一键重新生成。

错误

下表用于创建失败或查询本身失败时的 HTTP 错误。已受理任务的生成失败则返回 HTTP 200，详见上面的失败任务示例。始终同时检查 HTTP 状态、任务 status 与 error.code。

用量

curl "https://api.nightferry.io/v1/usage/video?since=2026-09-01&until=2026-09-05" \
  -H "Authorization: Bearer $NIGHTFERRY_KEY"

查询当前 Key 的视频用量，按模型、分辨率、渠道和参考视频类别分组，成功与失败任务数及两个 token 计数分别统计。日期按 UTC，格式为 YYYY-MM-DD；until 不含当天，默认窗口是最近 30 天，含当天。请按自己的测试日期调整示例窗口。

美元计费与核账

两列价格二选一：请求含参考视频就用“有参考视频”，否则用“无参考视频”。费用等于经过验证的 completion_tokens × 任务接受时锁定的每百万 token 美元价格 ÷ 1,000,000，四舍五入至六位美元小数。total_tokens 单独保留，不再加收。例如 Mini 480p、无参考视频、40,594 个 completion token，收费 $0.137303。

文字、视频和所有密钥共用账户余额。创建视频先占款，交付成功且用量可信后扣费并释放占款；明确失败则释放占款，不收成功费用。用量缺失、结果未知或视频复制中断，会保留为待核账并继续占款。欠款时仍可查询任务、查看 Console 和充值。新的视频请求按账户可用余额放行；可用余额须覆盖本次预扣，不足时返回 402 insufficient_credit。

任务响应新增 channel 和 billing。后者含 currency、state（held 占款、pending 待核账、settled 已扣费、released 已释放）、charge_usd、billable_tokens 与 backfilled。held 或 pending 时，费用为 null 表示尚未核定，不代表免费；released 时表示占款已释放，不收本次生成费用。历史成功任务在归属、用量和类别证据齐备后补收费，可能产生负余额。

GET /v1/usage/video 按模型、分辨率、渠道和参考视频类别分组。每组和汇总含 pending、billable_tokens 与 charge_usd；pending 包含占款中和待核账任务，金额只统计已扣费用，使用保留六位小数的美元字符串。GET /v1/usage 提供账户余额、占款和可用余额。

Mini/Fast 1080p 使用前请向我们确认适用的固定美元价格。未配置时，在生成前返回 409 pricing_unavailable。

测试与验收

• 用已有 Key 创建任务。测试海外 NSFW 时指定 channel: overseas；检查响应中的渠道，记录任务 id、模型和请求规格。
• 轮询到最终状态。只有 status: succeeded 且成片符合你的需求，才算生成测试通过。创建成功或查询返回 HTTP 200 都不等于生成通过。
• 核对同一任务的 billing.state、billable_tokens 和 charge_usd。已扣费应显示 settled；待核账则稍后再次查询。
• 在 Console 视频账单按任务 ID 对照费用，或使用上面的用量接口核对汇总。GET /v1/usage 可查账户总余额、占款与可用余额。

遇到不符合预期的结果，请保留任务 ID、模型、渠道、请求时间、HTTP 状态、任务状态和错误码，便于我们定位。无需提供 API Key。