YunShuAi API 文档

更新日期：2026-09-25（v1.5）

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

完整 API Key 只在创建或轮换时显示一次。请仅在服务端保存 Key，不要写入浏览器代码、网页源码、日志或公开仓库。每个 Key 的模型权限和钻石限额独立计算；限额不足时不会创建新任务。模型能力、时长、参考素材限制与计费方式均以当前模型目录为准。

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

请先读取模型目录，并使用返回的 id 作为请求中的 model。返回字段中的 type 用于区分 video 与 image；模型、分辨率、比例、时长、参考素材限制、billing_mode 与 customer_cost 均以接口返回为准。上游供应商、路由、并发策略和账号信息不属于 API 响应的一部分。

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

3. 上传与管理参考素材
POST /files
GET /files/{file_id}
GET /files/{file_id}/content

POST /files 支持 multipart/form-data 或原始二进制上传。原始二进制上传时使用 X-Media-Filename 指定文件名。支持图片、视频、音频，单个文件最大 20 MB；单个音频参考文件时长不超过 30 秒。上传成功会返回 file_... ID 与 expires_at。file_... 仅可由创建它的同一 API Key 使用，并在 expires_at 后失效。

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 使用 file_... ID；也支持 HTTPS 素材地址或 Base64 Data URL。请只提交当前业务自身的素材，素材地址不可用或已过期时请重新上传。

4. 视频模型
模型目录同时返回主视频模型、已启用的次视频模型及其独立能力。请使用 /models 返回的 model id，不要写死展示名称或参数。主视频模型固定 30 秒时无需传 duration；次视频模型的 duration、resolution、aspect_ratio 和 medias 数量必须符合该模型返回的 supported_* 与 max_*_references 字段。

billing_mode=per_second 表示按模型配置的秒数计费；per_request 表示按次计费。视频超分等独立视频能力也以其在模型目录中返回的参数为准。

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

请求字段：
model（必填，使用 /models 返回的视频模型 id）
prompt（必填，视频提示词）
resolution（可选；必须是该模型 supported_resolutions 之一）
aspect_ratio（可选；必须是该模型 supported_aspect_ratios 之一）
duration（次视频模型按 supported_durations 传入；主模型固定 30 秒时不传）
medias（可选；数量上限以该模型 max_*_references 为准）
Idempotency-Key（建议通过 HTTP Header 传入；每个业务请求使用唯一值）

同一 Idempotency-Key 在有效期内重复调用会返回第一次请求的任务，不会重复扣除钻石或重复创建任务；网络超时后请保留原 Key 重试。平台在后台完成素材传输、模型调度、供应商结果接收和轮询兜底；调用方只需保存任务 ID 并轮询状态，不需提供任何供应商凭据或回调地址。

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_example_0001" \
  -d '{"model":"video_model_id","prompt":"黄昏海边，镜头缓慢推进","resolution":"720p","aspect_ratio":"16:9","medias":["file_example_id"]}'

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

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

状态：processing（处理中）、succeeded（已完成）、failed（失败）。每 10 至 15 秒使用同一个任务 ID 查询一次；处理中请勿重复提交同一业务请求。服务端会按模型和供应商进行并发调度，并对临时查询错误进行退避重试；以本接口状态为最终判断，不以短时间内是否获取到结果地址判断失败。

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

结果尚未准备好时返回 409 result_not_ready，请继续轮询状态接口。

7. 图片模型
图片模型与视频模型使用同一 API Key。先通过 /models 获取 type=image 的模型 id，再调用：
POST /images/generations

图片模型支持的尺寸、比例及参考图数量以 /models 和 /capabilities 返回值为准。请求字段为 model、prompt、size、aspectRatio；可选 referenceImages 使用图片 Base64 Data URL，最多 3 张。

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":"image_model_id","prompt":"晨雾中的山谷","size":"1k","aspectRatio":"16:9"}'

成功响应会返回 jobId、url 与 imageUrl。图片生成失败时平台自动释放该次任务已冻结的钻石。

8. 并发与素材复用
接口支持并发创建多个异步任务。每个业务任务使用独立 Idempotency-Key；超时或 502 重试同一业务任务时继续使用原 Key。重复使用仍在有效期内的同一 file_... 可减少重复传输，但不会延长文件有效期，也不会改变它与 API Key 的归属关系。

9. 常见错误
401 invalid_api_key：检查 API Key 是否正确或已停用
403 model_not_allowed：当前 Key 未开通该模型
400 prompt_required：请提供提示词
400 invalid_reference_media：检查素材类型、数量、格式或 HTTPS 地址
400 external_file_unavailable：file_... 已过期或不属于当前 API Key，请重新上传
400 media_too_large：单个参考文件超过 20 MB
429 api_diamond_limit_exceeded：已达到该 Key 的钻石限额
404 generation_not_found：任务不存在或不属于当前 Key
409 result_not_ready：结果尚未生成，请继续轮询
502 服务暂时无法处理：保留原 Idempotency-Key，稍后使用原请求重试