跳至主要內容

视频接入 API 文档

小北团队2026/8/11大约 8 分钟

小北 API 的视频生成接口采用 Sora 异步任务格式，可直接接入 New API。本文涵盖模型选择、任务创建与查询、参考素材传递、错误排查等完整流程。

更新时间：2026-08-10

接入流程

创建视频任务 → 保存任务 ID → 轮询任务状态 → 下载生成的视频。

1. 基础地址与鉴权

Base URL

https://api.xbyjs.top

所有请求都需要在请求头中携带自己的 API Key：

Authorization: Bearer 你的_API_KEY

安全提示

请勿在前端代码、公开仓库或截图中暴露 API Key。

接口一览

方法路径用途
POST/v1/videos创建视频生成任务
GET/v1/videos/{task_id}查询任务状态与详情
GET/v1/videos/{task_id}/content下载已生成的视频

2. 视频模型

本站公开模型固定分辨率支持时长计费方式单价说明
sd-2.5-480p480p4～30 秒按秒¥0.4/秒Seedance 2.5；最多 30 图、10 音频、10 视频；支持真人
sd-2.5-720p720p4～30 秒按秒¥0.6/秒Seedance 2.5；最多 30 图、10 音频、10 视频；支持真人
PL-2.0-720p720p5、10、15 秒按次¥5/次Seedance 2.0；最多 9 图、3 音频、3 视频；支持真人
grok-imagine-video-1.5720p1～15 秒按次¥0.38/次Grok Imagine Video 1.5；最多 7 张参考图；支持真人
xingyao-2.0fast720p5、10、15 秒按次¥3.8/次Seedance 2.0 Fast；最多 4 图、3 视频、1 音频；支持真人、原生
xinghe-2.0s720p10～15 秒按次¥3.8/次Seedance 2.0 Fast；最多 9 图、3 音频、3 视频；支持真人、原生
xinqi-2.0-v2720p10、15 秒按次¥3/次Seedance 2.0 Fast；最多 9 图、3 音频、3 视频；人脸需自行处理（画网格）
xinqi-2.0-v4720p10 秒按次¥3.8/次Seedance 2.0；最多 9 图、3 音频、3 视频；支持真人
xinqi-2.0-v5720p10～15 秒按次¥5.8/次Seedance 2.0；最多 9 图、3 音频、3 视频；支持人脸、原生
MiniMax-H3待上线2～15 秒按秒待上线最多 9 图、3 视频、3 音频；即将推出
happyhorse-1.1待上线3～15 秒按秒待上线最多 9 张参考图；即将推出

模型名与计费

  • model 必须填写模型广场展示的本站公开模型名，不得填写渠道内部的上游模型名。
  • sd-2.5-480p 始终按 480p 处理，sd-2.5-720p 始终按 720p 处理。
  • 按秒计费模型的实际费用 = 对应分辨率的每秒单价 × 任务时长。
  • 渠道上游模型可由管理员独立映射，不影响下游公开模型名与价格。

完整请求示例

以下示例同时传入图片、视频和音频参考素材：

{
  "model": "sd-2.5-720p",
  "prompt": "女孩走在大街上，镜头平稳跟拍，真实自然光",
  "duration": 15,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "reference_images": [
    "https://example.com/ref-1.png"
  ],
  "reference_video_urls": [
    "https://example.com/ref-1.mp4"
  ],
  "reference_audio_urls": [
    "https://example.com/ref-1.mp3"
  ]
}

3. 文生视频

只传 prompt，不传图片、视频或音频素材，即为文生视频。

{
  "model": "xingyao-2.0fast",
  "prompt": "女孩走在大街上，镜头平稳推进，真实风格",
  "duration": 15,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}

4. 图生视频与参考图

如果要让视频参考图片，必须传入图片字段，推荐使用 reference_images。

参考素材地址

参考图必须使用公网可访问的 http/https URL。请勿传入本地文件路径、内网地址、Base64 或 data:image/...。

多图规则：

  • 单张参考图会按单图参考处理。
  • 多张参考图必须放在同一个数组中，图片顺序会原样保留。
  • 多人物场景建议在 prompt 中明确说明“参考图 1/2/3 分别是谁”。
{
  "model": "xinqi-2.0-v5",
  "prompt": "参考图1=陈砚，成年男性；参考图2=豆豆，小男孩；参考图3=念念，小女孩。夜晚长途大巴车厢内，三人必须同框出现，陈砚坐中间，豆豆躺在陈砚腿上，念念靠窗发呆。禁止少人，禁止人物合并，禁止新增陌生人物。",
  "duration": 15,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "reference_images": [
    "https://example.com/ref-1.png",
    "https://example.com/ref-2.png",
    "https://example.com/ref-3.png"
  ]
}

兼容图片字段

字段类型说明
reference_imagesstring[]推荐，参考图片数组
imagesstring[]兼容，参考图片数组
image_urlsstring[]兼容，图片 URL 数组
reference_image_urlsstring[]兼容，参考图片 URL 数组
referenceImagesstring[]驼峰写法
referenceImageUrls / referenceImageURLsstring[]驼峰写法
imagestring单张图片
image_urlstring单张图片 URL
reference_image / referenceImagestring单张参考图
reference_image_url / referenceImageUrl / referenceImageURLstring单张参考图 URL
input_reference / inputReference / inputReferenceURLstring单张输入参考图
first_frame_image / firstFrameImagestring首帧图
input_image / inputImagestring输入图

检查参考图是否传入成功

查询任务详情，查看 properties.input.reference_image_count：

{
  "reference_image_count": 9
}
  • 大于 0：参考图已成功传入。
  • 等于 0：本次请求没有传入可识别的图片字段，任务实际会按文生视频处理。

5. 参考视频

推荐使用 reference_videos：

{
  "model": "xingyao-2.0fast",
  "prompt": "参考视频中的运动方式生成新视频",
  "duration": 15,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "reference_videos": [
    "https://example.com/ref.mp4"
  ]
}

兼容字段：

  • videos
  • reference_videos
  • reference_video_urls
  • referenceVideos
  • input_video
  • inputVideo

6. 参考音频

推荐使用 reference_audio_urls：

{
  "model": "xingyao-2.0fast",
  "prompt": "根据音频节奏生成视频",
  "duration": 15,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "reference_audio_urls": [
    "https://example.com/ref.mp3"
  ]
}

兼容字段：

  • reference_audio_urls
  • reference_audios
  • referenceAudios
  • audio
  • audio_url
  • audios
  • input_audio
  • inputAudio

音频使用限制

音频不能作为唯一的参考素材单独传入，请同时提供其他受支持的输入。

7. 画幅、分辨率与时长

用途aspect_ratioresolutionduration
横屏16:9720p15
竖屏9:16720p15
方形1:1720p15

resolution 常用值为 480p、720p、1080p。

参数填写

  • aspect_ratio 只填写画幅，例如 16:9、9:16、1:1。
  • resolution 只填写清晰度，例如 480p、720p、1080p，也可以不传。
  • 不同模型支持的时长和固定分辨率不同，请以模型列表为准。

8. 创建、查询与下载任务

创建任务

创建成功后，接口会返回任务 ID：

{
  "id": "task_xxx",
  "object": "video",
  "status": "queued"
}

请保存返回的 id，后续查询与下载时将它作为 {task_id} 使用。

查询任务

GET /v1/videos/task_xxx

下载视频

任务完成后调用：

GET /v1/videos/task_xxx/content

9. curl 示例

文生视频

curl -X POST "https://api.xbyjs.top/v1/videos" \
  -H "Authorization: Bearer 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "xingyao-2.0fast",
    "prompt": "女孩走在大街上，镜头平稳推进，真实风格",
    "duration": 15,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

图生视频

curl -X POST "https://api.xbyjs.top/v1/videos" \
  -H "Authorization: Bearer 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "xinqi-2.0-v5",
    "prompt": "参考图1=陈砚，成年男性；参考图2=豆豆，小男孩；参考图3=念念，小女孩。夜晚长途大巴车厢内，三人必须同框出现，禁止少人，禁止人物合并。",
    "duration": 15,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "reference_images": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png",
      "https://example.com/ref-3.png"
    ]
  }'

查询任务

curl -X GET "https://api.xbyjs.top/v1/videos/task_xxx" \
  -H "Authorization: Bearer 你的_API_KEY"

下载视频

curl -L "https://api.xbyjs.top/v1/videos/task_xxx/content" \
  -H "Authorization: Bearer 你的_API_KEY" \
  -o output.mp4

10. 常见问题

No available channel for model

表示当前模型暂不可用，或 model 填写错误。

  • 到模型广场复制本站公开模型名。
  • 不要填写非本站公开模型名。
  • 检查账号分组是否支持该模型。

参考图没有生效

先查看任务详情中的 properties.input.reference_image_count：

  • 大于 0：参考图已经传入，生成效果由模型决定。多人物场景仍需在 prompt 中明确绑定每张参考图对应的人物。
  • 等于 0：请求没有传入可识别的图片字段，任务实际按文生视频处理。
  • 传入多张图时，优先确认请求体中包含一个 reference_images 数组；image_url 仅代表单图兼容入口。

reference image url must be a public http/https url

表示参考图地址不是公网 URL。请先把图片上传到公网可访问的地址，再传入：

{
  "reference_images": [
    "https://example.com/ref-1.png"
  ]
}

invalid_size

表示尺寸、画幅或分辨率参数错误。推荐写法：

{
  "aspect_ratio": "16:9",
  "resolution": "720p"
}

timeout / Read timed out / service returned error

表示视频生成过程中服务端超时或生成失败，可尝试：

  • 等当前任务结束后重新提交。
  • 减少参考图、参考视频或参考音频的数量。
  • 缩短提示词或降低任务复杂度。
  • 多次失败时更换同类模型重试。

任务失败后余额变多

视频任务一般会先预扣费用。任务失败后系统会自动退款，因此余额可能在任务失败确认后回补。这是异步任务的正常结算过程，并非重复充值。

查询余额与扣费记录

下游余额以本站控制台和使用日志为准：

  • 当前余额：登录本站控制台查看钱包余额。
  • 单次扣费：在使用日志中按任务 ID 查询。
  • 视频任务：先预扣，成功后确认扣费，失败后自动退款。
  • 任务刚失败时余额可能尚未回补，请等待退款同步完成后刷新。

接入方无需使用其他钱包或余额接口查询，只需使用本站控制台和本站 API Key。

错误信息说明

codemessage
invalid_request请求参数不符合模型要求，请检查时长、画幅、分辨率或参考素材
asset_processing_failed参考素材处理失败，请更换素材或重新上传后重试
content_policy_violation内容审核未通过，请调整提示词或更换参考素材
video_generation_failed视频生成失败，请稍后重试
service_unavailable模型服务暂时不可用，请稍后重试
request_timeout任务处理超时，请稍后重新提交

11. 接入检查清单

提交请求前，请确认：

  • [ ] baseURL 为 https://api.xbyjs.top。
  • [ ] 创建任务路径为 /v1/videos。
  • [ ] Authorization 使用自己的 API Key。
  • [ ] model 是模型广场展示的本站公开模型名。
  • [ ] 参考图片、视频与音频均为公网可访问的 http/https URL。
  • [ ] 音频没有作为唯一的参考素材单独传入。
  • [ ] aspect_ratio 与 resolution 已分开填写。
  • [ ] 查询任务时使用创建接口返回的 id。
  • [ ] 使用按次计费模型接入 New API 中转时，已按部署要求将模型加入任务价格白名单，避免计费异常。

New API Docker 环境变量示例：

TASK_PRICE_PATCH=seedance-1.5-pro-12s
最近更新:
贡献者: lfglfg11
小北 API | Copyright © 2026 小北团队
Copyright © 2026 小北团队