视频制作

YunShuAi API 文档

更新日期：2026-09-17（v1.2）

1. 接入信息
标准 Base URL：https://api.yunshuai.top/api/v1
兼容 Base URL：https://api.yunshuai.top/v1
鉴权：Authorization: Bearer ysf_your_api_key_here
响应格式：JSON

这是统一的聚合接口。模型目录会返回当前已启用的视频和图片模型，具体能力、尺寸、比例以接口返回为准。完整 API Key 仅在创建或轮换时显示一次，请保存在服务端密钥管理中，不要写入浏览器代码、网页源码、日志或公开仓库。

2. 鉴权与计费
所有请求均须携带：
Authorization: Bearer ysf_your_api_key_here

每个 API Key 可设置独立限额，0 表示不限额。余额不足、Key 未启用、超过限额或模型未授权时，任务不会创建。失败任务按平台规则结算。

3. 获取模型与能力
GET /models
GET /capabilities

curl https://api.yunshuai.top/api/v1/models \
  -H "Authorization: Bearer ysf_your_api_key_here"

模型目录同时返回主视频模型、已启用的次视频模型和图片模型。请始终使用 /models 返回的 model id 发起请求。返回的 type 用于区分 video 与 image；视频模型的 supported_resolutions、supported_durations、max_*_references、billing_mode 与 customer_cost 是该模型的唯一有效参数和计费依据。

主视频模型 seedance2.5 满血固定30s,30图10音频1视频 固定 30 秒。次视频模型独立计费、独立执行，不会进入主模型链路；例如当前启用的 1080P 次模型支持 4 至 15 秒、按秒计费、最多 9 张图片、3 个视频和 3 个音频参考。模型配置可能更新，接入方每次选择模型前应重新读取 /models。

4. 上传参考素材
POST /files
Content-Type：multipart/form-data 或原始二进制
GET /files/{file_id}
GET /files/{file_id}/content

支持图片、视频、音频。单个文件最大 20 MB；单个音频参考文件时长不超过 30 秒。上传成功会返回 file_... ID 与 expires_at。文件仅属于创建它的 API Key，默认在 2 小时后过期。原始二进制上传时请通过 X-Media-Filename 指定文件名。

curl https://api.yunshuai.top/api/v1/files \
  -X POST \
  -H "Authorization: Bearer ysf_your_api_key_here" \
  -F "file=@reference.png"

响应示例：
{"id":"file_example_id","object":"file","filename":"reference.png","mime_type":"image/png","bytes":123456,"expires_at":1780000000}

medias 支持 Base64 Data URL 和 file_... ID。主模型还可使用 HTTPS 素材地址；次视频模型请使用 file_... ID 或画布上传生成的平台素材地址，避免第三方链接过期或不可访问。请只提交客户自身的参考素材；文件过期后需重新上传。

5. 提交视频任务
POST /video/generations

请求字段：
model（必填，使用目录中 type=video 的模型）
prompt（必填，视频提示词）
resolution（可选，必须是该模型 supported_resolutions 之一）
aspect_ratio（可选，必须是该模型 supported_aspect_ratios 之一）
duration（次视频模型可选或必填，必须是该模型 supported_durations 之一）
medias（可选，参考素材数组；数量上限以该模型 max_*_references 为准）
Idempotency-Key（建议通过 HTTP Header 传入；每个业务请求使用唯一值）

主视频模型时长固定为 30 秒，无需传入 duration。次视频模型须按模型目录的 supported_durations 传入 duration；billing_mode=per_second 表示按秒计费，per_request 表示按次计费。

请求示例：
curl https://api.yunshuai.top/api/v1/video/generations \
  -X POST \
  -H "Authorization: Bearer ysf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260914-001" \
  -d '{"model":"video_model_id","prompt":"黄昏海边，镜头缓慢推进","resolution":"1080p","aspect_ratio":"16:9","duration":5,"medias":["file_example_id"]}'

提交成功响应示例：
{"id":"task_example_id","object":"video.generation","status":"processing","model":"video_model_id","resolution":"720p","aspect_ratio":"16:9"}

提交成功返回 processing。调用方只需按任务 ID 轮询；同一业务请求必须复用同一个 Idempotency-Key。

6. 提交图片任务
POST /images/generations

请求字段：
model（必填，使用目录中 type=image 的模型）
prompt（必填，图片描述）
size（可选，必须是模型返回的 sizes 之一）
aspectRatio（可选，必须是模型返回的 supported_aspect_ratios 之一）
referenceImages（可选，图片 Base64 Data URL 数组）
mode（可选：text、character、storyboard、cinematicShot）

curl https://api.yunshuai.top/api/v1/images/generations \
  -X POST \
  -H "Authorization: Bearer ysf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2 2K","prompt":"电影级室内肖像","size":"2048x2048","aspectRatio":"1:1"}'

成功响应包含 jobId、imageUrl 和 credits。图片任务失败会自动退回本次扣除的💎。

7. 查询视频状态与获取结果
GET /video/generations/{id}
GET /video/generations/{id}/result

状态：processing（处理中）、succeeded（已完成）、failed（生成失败）。请使用同一个任务 ID 每 10 至 15 秒查询一次；processing 状态下不要重复提交。

结果接口响应示例：
{"id":"task_example_id","object":"video.result","urls":["https://result.example/video.mp4"]}

结果尚未准备好时返回 409 result_not_ready，请继续轮询状态接口。任务完成后使用 result 接口获取最终地址。

8. 接入顺序
模型读取 → 素材上传 → 任务提交 → 状态轮询 → 结果下载。
接入方应保留任务 ID，并在网络重试时复用 Idempotency-Key。

9. 常见错误
401 invalid_api_key / auth_required：检查 Key 是否正确、已轮换或已停用
403 model_not_allowed：该 Key 未授权当前模型；重新读取 /models 后选择已授权模型
400 prompt_required / image_prompt_required：请提供提示词
400 image_ratio_unavailable：当前图片模型不支持该比例，请读取模型目录
400 video_parameter_unavailable / video_duration_unavailable：当前视频模型不支持所选分辨率、比例或时长；请重新读取 /models
400 customer_credit_insufficient：余额不足，请充值后重新提交
429 api_diamond_limit_exceeded：已达到该 Key 的💎限额
404 generation_not_found：任务不存在或不属于当前 Key
409 result_not_ready：结果尚未生成，请继续轮询
400 invalid_reference_media / external_file_unavailable：参考素材格式无效、文件已过期或不属于当前 API Key；请重新上传后使用新的 file_... ID
400 secondary_reference_requires_file_upload：次视频模型的参考素材必须先通过 /files 或画布上传接口上传
400 media_too_large：单个参考文件超过 20 MB
502 服务暂时无法处理：请保留原 Idempotency-Key，稍后使用原请求重试
任务状态 failed：查看状态接口的 error 字段；使用新的业务请求和新的 Idempotency-Key 重新发起