API 文档
点击下方按钮复制完整文档
YunShuAi API 文档
更新日期：2026-09-29
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 绑定一个客户账号。任务受理成功后从该账号的钻石余额扣除；Key 的钻石限额是独立上限，0 表示不限额。余额不足、Key 未启用、超过限额或模型未授权时，任务不会创建。符合退款条件的失败任务会自动退回原账号。
3. 获取模型与能力
GET /models
GET /capabilities
curl https://api.yunshuai.top/api/v1/models \
-H "Authorization: Bearer ysf_your_api_key_here"
当前目录由服务器实时返回，包含主模型以及后台已启用的第三方视频/图片模型；模型名称、系列、分辨率、时长和参考素材能力以本次返回值为准。不要在客户端写死模型列表。
图片模型返回各自支持的 sizes、supported_aspect_ratios 和 customer_cost。请先读取 /capabilities，再按模型返回值渲染控件；不要把视频参数发送给图片模型，也不要把图片尺寸发送给视频模型。
4. 上传参考素材
POST /files
Content-Type：multipart/form-data 或原始二进制
支持图片、视频、音频。单个文件最大 20 MB；单个音频参考文件时长不超过 30 秒。上传成功会返回 file_... ID，可放入视频任务的 medias 数组，或在业务侧保存后继续使用。
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}
medias 同时支持 HTTPS 素材地址、Base64 Data URL 和 file_... ID。文件按 API Key 隔离，过期后需重新上传。
5. 提交视频任务
POST /video/generations
请求字段：
model（必填，使用目录中 type=video 的模型）
prompt（必填，视频提示词）
resolution（可选：480p、720p、1080p；默认 480p）
aspect_ratio（可选，默认 16:9）
duration / video_duration（第三方视频模型可选，范围和可用值以该模型目录的 durations 为准；主模型固定 30 秒）
medias（可选，参考素材数组，最多 52 条）
idempotency_key（建议，每个业务请求使用唯一值）
主模型支持比例：1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、2:1、1:2、3:1、1:3、21:9、9:21，时长固定为 30 秒。第三方视频模型的比例、分辨率、时长和参考素材数量以 /models 返回的该模型能力为准；若目录返回 durations，请从中选择并传入 duration（服务端会校验范围）。
第三方视频模型使用目录返回的 model 值提交，服务端会按该模型绑定的供应商和上游模型 ID 路由；不要把第三方模型改写成 seedance 2.5，也不要混用主模型账号池的素材 ID。第三方模型支持的参数以模型目录返回值为准。
提交成功返回 processing。上游高峰期可能需要较长时间，请持续轮询，不要因为短时间未完成而重复提交；同一业务请求必须复用同一个 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（生成失败）、review（结果核对中）。请使用同一个任务 ID 每 10 至 15 秒查询一次；processing 或 review 状态下不要重复提交。
结果接口响应示例：
{"id":"task_example_id","object":"video.result","urls":["https://result.example/video.mp4"]}
结果尚未准备好时返回 409 result_not_ready，请继续轮询状态接口。任务完成后使用 result 接口获取最终地址。
8. 兼容画布接入
使用 /v1 路径的画布：Base URL 填写兼容 Base URL，其余路径保持不变。
使用 Melius 协议的画布：Base URL 填写标准 Base URL；模型发现接口为 GET /generation/models，返回视频和已启用图片模型。系统支持模型读取、项目、节点、分片素材上传、运行状态和结果下载。
标准验收顺序：模型读取 → 素材上传 → 任务提交 → 状态轮询 → 结果下载。接入方应保留任务 ID，并在网络重试时复用 Idempotency-Key。
9. 常见错误
401 invalid_api_key / auth_required：检查 Key 是否正确、已轮换或已停用
403 model_not_allowed：该 Key 未授权当前模型；重新读取 /models 后选择已授权模型
400 model_not_available：模型已授权但当前后台未启用或供应商配置不可用；请刷新 /models 后重试
400 prompt_required / image_prompt_required：请提供提示词
400 image_ratio_unavailable：当前图片模型不支持该比例，请读取模型目录
400 账户钻石余额不足：请充值后重新提交
429 api_diamond_limit_exceeded：已达到该 Key 的钻石限额
404 generation_not_found：任务不存在或不属于当前 Key
409 result_not_ready：结果尚未生成，请继续轮询
502 服务暂时无法处理：请使用原 Idempotency-Key 稍后重试
