开发者平台 / v1
把生成能力接入你的产品。
一套 API 覆盖图片、视频和动作生成。上传素材、创建任务，然后轮询获取结果。
管理 API 密钥- 01上传参考素材
- 02创建生成任务
- 03查询任务状态
- 04下载生成结果
每个请求都需要鉴权
通过 Bearer Token 发送密钥。密钥归属于当前账户，绝不会放入 URL。
每次生成消耗 2 积分，与工作台共用同一个账户余额。
每 3 秒查询一次，直到状态为 succeeded 或 failed。目前不提供 Webhook。
每个 API 密钥每分钟最多可发送 60 个请求。
创建任务必须携带 8–128 位 URL 安全字符的 Idempotency-Key；相同请求可以安全重试。
shell
export API_KEY="your_api_key"
curl https://your-domain.example/api/v1/models \
-H "Authorization: Bearer $API_KEY"02 / 接口说明
接口
GET
/api/v1/models查看能力 · 返回 { models }
POST
/api/v1/uploads上传一个参考文件 · 返回 { upload }
POST
/api/v1/generations创建生成任务 · 返回 { generation }
GET
/api/v1/generations?page=1&pageSize=20返回 { items, total, page, pageSize }
GET
/api/v1/generations/{id}查询任务 · 返回 { generation }
GET
/api/v1/media/{id}?download=1下载当前账户的媒体；去掉查询参数则在线查看
支持的输入
- 图片：JPEG、PNG、WebP · 最大 10 MiB
- 视频：MP4、MOV · 最大 10 MiB
- 动作：必须是 1 张图片 + 1 个视频；Wan 视频最大 10 MiB
可用模型
- 图片
- nano-banana-2 · gpt-image-2
- 视频
- veo-3.1-fast · 8 秒 · 720p · 16:9 或 9:16
- 动作
- kling-2.6-motion-control（必须填写提示词）· wan-2.2-animate-replace / wan-2.2-animate-move（省略提示词）
生成请求字段
- kind
- 必填
- image、video 或 motion
- model
- 必填
- GET /models 返回的兼容模型 ID
- prompt
- 取决于模型
- 支持文本的图片/视频模型及 Kling 必须填写非空提示词，最多 4,000 字符。Wan 必须省略；传入非空提示词会被拒绝。
- aspectRatio
- 必填
- 模型支持的画面比例
- referenceUploadIds
- 可选
- POST /uploads 返回的 ID 数组
- generationType
- 可选
- 仅视频任务可用；图片和动作任务请省略
常见响应状态
- 401
- API 密钥缺失、无效或已过期
- 402
- 账户积分不足，无法创建任务
- 403
- 当前测试环境不允许该账户访问
- 409
- 幂等键已用于内容不同的请求
- 413
- JSON 请求或上传文件过大
- 429
- 该密钥超过每分钟 60 次请求的限制
upload reference
curl -X POST https://your-domain.example/api/v1/uploads \
-H "Authorization: Bearer $API_KEY" \
-F "file=@character.png"create generation
curl -X POST https://your-domain.example/api/v1/generations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: reel-2026-11-06-001" \
-d '{
"kind": "video",
"model": "veo-3.1-fast",
"prompt": "A quiet cinematic orbit around the subject",
"aspectRatio": "9:16",
"referenceUploadIds": ["upload_id"],
"generationType": "REFERENCE_2_VIDEO"
}'poll result
curl https://your-domain.example/api/v1/generations/generation_id \
-H "Authorization: Bearer $API_KEY"succeeded response
{
"generation": {
"id": "generation_id",
"status": "succeeded",
"progress": 100,
"error": null,
"output": {
"mediaId": "media_id",
"viewUrl": "/api/v1/media/media_id",
"downloadUrl": "/api/v1/media/media_id?download=1"
}
}
}download output
curl -L "https://your-domain.example/api/v1/media/media_id?download=1" -H "Authorization: Bearer $API_KEY" -o output.mp403 / API 密钥
为不同集成创建独立密钥
开发、自动化和生产环境可以使用不同密钥，登录后可随时查看已保存的完整密钥。