suno API 模型解析指南
快速结论
- suno supports Text-to-Video, Image-to-Video, R2V, and Video Edit in one workflow.
- Use this model guide page to validate parameters with minimal request/response examples.
- Stabilize prompts here first, then move to production API integration.
核心能力
- Unified multi-mode testing：Switch across Text-to-Video, Image-to-Video, R2V, and Video Edit in one place.
- Parameter-first validation：Iterate quickly on prompts, durations, and references before production rollout.
- Production-ready handoff：Minimal request/response structure helps you move stable configs into API workflows.
适用场景
- When you need fast iteration across multiple generation modes.
- When you need to validate parameters and error handling before integration.
不适用场景
- For large-scale async batch production, use the server-side API pipeline directly.
- For strict auth/audit requirements, prioritize backend orchestration.
运行特性
- This model guide page is optimized for interaction and parameter rehearsal.
- The output panel demonstrates task result structure for integration guidance.
最小请求示例
{
"model": "suno",
"mode": "text-to-video",
"input": {
"prompt": "A cinematic city sunrise with soft fog and moving traffic.",
"duration": 5
}
}
最小响应示例
{
"task_id": "task_xxxxxxxx",
"model": "suno",
"mode": "text-to-video",
"status": "queued",
"created_at": "2026-04-15T00:00:00.000Z"
}
关键参数
| 参数 | 类型 | 必填 | 默认值 | 范围 | 说明 |
|---|---|---|---|---|---|
| model | string | 是 | suno | - | Model identifier. Use the fixed value suno. |
| prompt | string | 是 | - | - | Main instruction describing the subject, action, scene, and style. |
| aspect_ratio | string | 否 | 16:9 | 16:9 | 9:16 |
| duration | integer | 否 | 6 | 5 | 10 |
| resolution | string | 否 | 720P | 720P | Output resolution. Defaults to 720P; supports 720P. |
常见错误
| HTTP | Code | 触发条件 | 修复建议 | 重试策略 |
|---|---|---|---|---|
| 400 | invalid_request_error | Request payload misses required fields or has invalid field types. | Validate model, mode, and input schema before request. | Retry only after fixing payload; avoid blind retries. |
| 401 | authentication_error | Missing Authorization header or invalid API key. | Verify Bearer token format and API key scope. | Retry after auth fix; rotate key if repeated failures continue. |
| 429 | rate_limit_exceeded | Request rate, concurrency, or current quota hits upstream rate limiting. | Apply exponential backoff first, then review request rate, concurrency, and quota usage. | Use exponential backoff (e.g., 1s/2s/4s) with jitter; if it persists, reduce submission pressure. |
| 500 | internal_error | Transient upstream error or internal processing failure. | Capture request id and trigger retry workflow. | Retry 2-3 times with short delays; escalate if persistent. |
FAQ
- When should I use suno?
Use it to validate video concepts quickly, compare mode behavior, and converge prompts before API rollout. - How do I choose Text-to-Video vs Image-to-Video?
Use Text-to-Video when you only have instructions; use Image-to-Video when you already have key frames or composition. - What is the difference between R2V and Video Edit?
R2V focuses on reference-guided generation, while Video Edit focuses on modifying existing video assets. - 图像视频模型报错：invalid apitype: -1
这类错误通常说明接口走错了。图像和视频模型一般不走 chat 接口，而是按对应文档发起 HTTP 任务请求，并通过任务状态接口轮询结果。排查时建议先看用户的实际请求代码、请求地址和请求体。 - 用户进行生成图片/视频的任务时出现任务失败，但是扣款
先让用户提供任务日志或截图，重点看是否出现了输入或输出 token 统计。如果有这类 token 记录，大概率是用户把图片/视频模型走成了 chat 接口；这不是正确用法。图片和视频模型通常是异步任务接口，需要通过 HTTP 请求先提交任务，再拿到任务 ID 轮询状态，详细以对应文档为准。