视频

文生视频与图生视频，提供国内和海外两个渠道。创建任务、轮询状态，完成后从一个约 24 小时内有效的链接取回视频。

接口地址

任务 ID 是不透明字符串，请原样保存。

国内与海外渠道

海外渠道支持 NSFW。渠道由 Key 决定，而不是由请求决定：国内 Key 始终走国内渠道，海外 Key 始终走海外渠道。请求中没有 channel 字段，两个渠道之间也不会自动切换。

两个渠道使用相同的模型 ID，按相同的固定美元价格计费。需要同时使用两个渠道时，请各持一个 Key。

模型

model 为必填。模型不支持的分辨率会在计费前被拒绝。-1 表示由模型自行决定时长。

创建任务

将 NIGHTFERRY_KEY 设为你的视频 Key。示例使用 Mini、480p、4 秒、不生成音频。

curl -X POST https://api.nightferry.io/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NIGHTFERRY_KEY" \
  -d '{
  "model": "doubao-seedance-2-0-mini-260615",
  "prompt": "a cat running through long grass, cinematic",
  "seconds": 4,
  "metadata": {
    "resolution": "480p",
    "ratio": "16:9",
    "generate_audio": false
  }
}'

创建会在视频完成前返回任务：

{
  "id": "task_8Qm2cVhK4pZr7TnW1yLs9XbE6dFa3JoU",
  "object": "video",
  "model": "doubao-seedance-2-0-mini-260615",
  "status": "queued",
  "progress": 0,
  "created_at": 1790700000
}

使用参考图片

参考素材以 URL 形式放在 metadata.content 中，不支持上传文件。每一项为 image_url、video_url 或 audio_url，可带可选的 role： first_frame、last_frame、reference_image、 reference_video 或 reference_audio。请使用服务可以访问的 HTTPS URL。

curl -X POST https://api.nightferry.io/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NIGHTFERRY_KEY" \
  -d '{
  "model": "doubao-seedance-2-0-mini-260615",
  "prompt": "the cat turns and walks toward the camera",
  "seconds": 4,
  "metadata": {
    "resolution": "480p",
    "ratio": "16:9",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/cat.png"}, "role": "first_frame"}
    ]
  }
}'

轮询任务

curl https://api.nightferry.io/v1/videos/task_8Qm2cVhK4pZr7TnW1yLs9XbE6dFa3JoU \
  -H "Authorization: Bearer $NIGHTFERRY_KEY"

轮询间隔不要短于 5 秒。status 为 queued、in_progress、 completed 或 failed；progress 取值 0 到 100。

{
  "id": "task_8Qm2cVhK4pZr7TnW1yLs9XbE6dFa3JoU",
  "object": "video",
  "model": "doubao-seedance-2-0-mini-260615",
  "status": "completed",
  "progress": 100,
  "created_at": 1790700000,
  "completed_at": 1790700180
}

失败的任务为 status: failed，并带有 error 对象。其中的消息是视频服务自身的原文，原样转发——可能是中文或英文，也可能引用内部任务编号。请以 status 为准，不要解析消息文本。

GET /v1/tasks/{id} 以另一种格式回答同一问题：status 为 QUEUED、IN_PROGRESS、SUCCESS 或 FAILURE， progress 为字符串，例如 "50%"，失败时带有 fail_reason。

创建后 24 小时仍未完成的任务会被标记为失败，冻结金额全额释放。

视频文件

curl https://api.nightferry.io/v1/tasks/task_8Qm2cVhK4pZr7TnW1yLs9XbE6dFa3JoU/artifacts \
  -H "Authorization: Bearer $NIGHTFERRY_KEY"

{
  "task_id": "task_8Qm2cVhK4pZr7TnW1yLs9XbE6dFa3JoU",
  "artifacts": [
    {
      "key": "video",
      "type": "video",
      "content_url": "https://api.nightferry.io/v1/tasks/task_8Qm2cVhK4pZr7TnW1yLs9XbE6dFa3JoU/artifacts/video/content?access=…"
    }
  ]
}

content_url 不需要 API Key——可以直接交给浏览器或播放器。请把这个 URL 本身当作凭证：任何持有它的人都能观看视频。

任务完成后，视频约 24 小时内可用。链接本身不会过期，但超过这个时间后，其背后的视频已不存在，请求会失败。需要保留的视频请及时下载。我们不保留副本。

使用 Key 时，GET /v1/videos/{id}/content 返回相同的内容。如果任务还生成了尾帧，会列出第二个 artifact：last_frame。

美元计费与费用核对

价格页中的两列价格二选一：请求包含参考视频时使用“有参考视频”，否则使用“无参考视频”。费用为 completion_tokens × 该模型每百万 Token 的美元单价 ÷ 1,000,000，四舍五入到微美元。例如 Mini 480p 无参考视频、completion_tokens 为 40,594 时，费用为 $0.137303。

• 创建时按分辨率与 seconds 估算并冻结金额，按该分辨率的 16:9 画面计算。Mini 480p 4 秒冻结 $0.129984。可用余额不足时创建会被拒绝，不产生费用。
• 完成时按上报的 completion_tokens 结算，与冻结金额的差额多退少补。
• 任务失败时全额释放。
• 两种例外。已完成的任务只上报 total_tokens、没有 completion_tokens 时，按 total_tokens 计费。完全没有上报用量时，创建时冻结的金额即为最终费用。

文本与视频共用一个账户余额。余额与每一笔费用（包括每个视频任务）都可以在 国内预览说明 中查看。

错误

任务受理后生成失败，会以 HTTP 200 和 status: failed 返回，如上所示。下表的 HTTP 状态表示请求本身被拒绝。请根据 HTTP 状态判断，不要依赖消息文本，消息可能是中文或英文。

测试与验收

• 使用所测渠道对应的 Key 创建任务，记录任务 id、模型与参数。
• 轮询直到 completed 或 failed。只有 completed 且交付的视频符合需求才算通过；仅创建成功不算。
• 在 24 小时内通过 content_url 取回视频。
• 在 Console 中核对任务与费用。

如果结果与预期不符，请保留任务 ID、模型、渠道、请求时间、HTTP 状态与任务状态，以便我们排查。请勿提供你的 API Key。