> ## Documentation Index > Fetch the complete documentation index at: https://docs.apistable.com/llms.txt > Use this file to discover all available pages before exploring further. # 生成音乐 > 写下想表达的内容，用风格或参考素材确定方向；自定义模式可以直接填写歌词。 > 能力按服务端配置逐项启用。未启用操作返回 503 且不创建任务；音乐积分扣除当前未启用。 ## 调用步骤 写下想表达的内容，用风格或参考素材确定方向；自定义模式可以直接填写歌词。 * 1. 按下方示例准备输入，将占位地址和 ID 换成你有权使用的资源。 * 2. 将 model 设为 suno\_generate，参数放在 input 内。提交一次并保存返回的 task\_id。 * 3. 查询已保存的任务，或接收回调。任务仍在处理中时继续等待，不重新提交同一操作。 * 从 result.data.data 读取作品。每首歌曲都有独立的本站 id，后续任务可将其作为 audio\_id。 ## 创建任务 将model和input发送到统一任务入口；可在顶层传公开HTTPS callback\_url。资源ID均为本账户的本站ID。当前音乐积分扣除未启用。 ```json theme={null} { "model": "suno_generate", "input": { "model": "V6", "custom_mode": true, "instrumental": false, "title": "Paper boats at dawn", "style": "Fingerpicked guitar, gentle brushed drums", "lyrics": "[Verse]\nWe fold a map into a boat\nAnd let the morning carry it home" } } ``` ## 受理响应 HTTP 200仅表示受理。查询GET /api/v1/tasks/\{task\_id}，直到data.status为succeeded或failed。成功后读取data.result；失败原因位于data.message。 ```json theme={null} { "code": 200, "msg": "success", "data": { "task_id": "YOUR_TASK_ID" } } ``` ## 参数速查 | 字段 | 类型 | 必填 | 说明与限制 | | - | - | - | - | | lyrics | string | 否 / 依条件 | 最多5000字符。自定义模式传入时优先于prompt；简单模式与prompt同时使用，非空歌词计为一个附件。 maxLength: 5000 | | prompt | string | 否 / 依条件 | 简单模式：最多3000字符的描述，与lyrics同时使用。自定义模式：最多5000字符的备用歌词，仅省略lyrics时使用。 maxLength: 5000 | | style | string | 否 / 依条件 | 音乐风格，最多 1000 字符；简单生成时计为一个附件。 maxLength: 1000 | | negative\_tags | string | 否 / 依条件 | 排除的风格；增加伴奏或人声时必填。 maxLength: 1000 | | vocal\_gender | string | 否 / 依条件 | m 或 f，表示人声倾向，不保证特定声音身份；生成时仅限自定义模式。 values: m, f | | style\_weight | number | 否 / 依条件 | 风格影响程度，0–1，最多两位小数；生成时仅限自定义模式。 min: 0; max: 1 | | weirdness\_constraint | number | 否 / 依条件 | 创意约束，0–1，最多两位小数；生成时仅限自定义模式。 min: 0; max: 1 | | audio\_weight | number | 否 / 依条件 | 音频影响程度，0–1，最多两位小数；生成时仅限自定义且非纯音乐模式。 min: 0; max: 1 | | variety | integer | 否 / 依条件 | 多样性，0–4 整数，自定义生成默认 1。 min: 0; max: 4 | | persona\_id | string | 否 / 依条件 | 本站 Voice 或 Persona ID；供应商 root 和原曲映射由后台处理。 maxLength: 200 | | persona\_model | string | 否 / 依条件 | style\_persona 或 voice\_persona，须与资源真实来源匹配。 values: style\_persona, voice\_persona | | max\_mode | boolean | 否 / 依条件 | PayAPI 扩展；Max 模式可能增加上游费用。本站积分扣除当前未启用。 default: false | | model | string | 是 | Suno 版本：V6、V6\_MINI 或 V6\_WILD；续写需与生成原曲版本一致。 values: V6, V6\_MINI, V6\_WILD | | custom\_mode | boolean | 是 | 自定义模式使用标题、歌词和风格；简单模式使用描述与参考附件。 | | instrumental | boolean | 是 | 生成纯音乐；纯音乐续写不传 prompt、lyrics 和 vocal\_gender。 | | title | string | 否 / 依条件 | 标题。生成/翻唱最多 80 字符，续写及其他操作最多 100 字符；自定义生成必填。 maxLength: 80 | | duration | number | 否 / 依条件 | 期望时长 10–360 秒；仅自定义生成，省略时自动决定。 min: 10; max: 360 | | image\_urls | array | 否 / 依条件 | 仅简单模式，最多 5 个公开 JPEG/PNG/WebP/BMP URL，每个最多 10 MiB。 maxItems: 5 | | video\_urls | array | 否 / 依条件 | 仅简单模式，最多 1 个公开 MP4/MOV/WebM URL，最多 100 MiB、241 秒。 maxItems: 1 | | audio\_urls | array | 否 / 依条件 | 简单模式参考音频 URL，每个 6–1800 秒、最多 500 MiB；含风格和歌词在内的总附件数量须为 1–10。 maxItems: 10 | ## 输入与限制 下方Schema列出支持字段、类型和基础限制；还须遵守“重要条件”，跨字段与来源资源校验不完全体现在JSON Schema中。未知参数会被拒绝。URL 参数仅接受公开 HTTPS 地址，不接受文件对象。 ```json theme={null} { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "lyrics": { "type": "string", "maxLength": 5000, "description": "最多5000字符。自定义模式传入时优先于prompt；简单模式与prompt同时使用，非空歌词计为一个附件。" }, "prompt": { "type": "string", "maxLength": 5000, "description": "简单模式：最多3000字符的描述，与lyrics同时使用。自定义模式：最多5000字符的备用歌词，仅省略lyrics时使用。" }, "style": { "type": "string", "maxLength": 1000, "description": "音乐风格，最多 1000 字符；简单生成时计为一个附件。" }, "negative_tags": { "type": "string", "maxLength": 1000, "description": "排除的风格；增加伴奏或人声时必填。" }, "vocal_gender": { "type": "string", "enum": [ "m", "f" ], "description": "m 或 f，表示人声倾向，不保证特定声音身份；生成时仅限自定义模式。" }, "style_weight": { "type": "number", "minimum": 0, "maximum": 1, "description": "风格影响程度，0–1，最多两位小数；生成时仅限自定义模式。" }, "weirdness_constraint": { "type": "number", "minimum": 0, "maximum": 1, "description": "创意约束，0–1，最多两位小数；生成时仅限自定义模式。" }, "audio_weight": { "type": "number", "minimum": 0, "maximum": 1, "description": "音频影响程度，0–1，最多两位小数；生成时仅限自定义且非纯音乐模式。" }, "variety": { "type": "integer", "minimum": 0, "maximum": 4, "description": "多样性，0–4 整数，自定义生成默认 1。" }, "persona_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "本站 Voice 或 Persona ID；供应商 root 和原曲映射由后台处理。" }, "persona_model": { "type": "string", "enum": [ "style_persona", "voice_persona" ], "description": "style_persona 或 voice_persona，须与资源真实来源匹配。" }, "max_mode": { "default": false, "type": "boolean", "description": "PayAPI 扩展；Max 模式可能增加上游费用。本站积分扣除当前未启用。" }, "model": { "type": "string", "enum": [ "V6", "V6_MINI", "V6_WILD" ], "description": "Suno 版本：V6、V6_MINI 或 V6_WILD；续写需与生成原曲版本一致。" }, "custom_mode": { "type": "boolean", "description": "自定义模式使用标题、歌词和风格；简单模式使用描述与参考附件。" }, "instrumental": { "type": "boolean", "description": "生成纯音乐；纯音乐续写不传 prompt、lyrics 和 vocal_gender。" }, "title": { "type": "string", "maxLength": 80, "description": "标题。生成/翻唱最多 80 字符，续写及其他操作最多 100 字符；自定义生成必填。" }, "duration": { "type": "number", "minimum": 10, "maximum": 360, "description": "期望时长 10–360 秒；仅自定义生成，省略时自动决定。" }, "image_urls": { "maxItems": 5, "type": "array", "items": { "type": "string", "format": "uri" }, "description": "仅简单模式，最多 5 个公开 JPEG/PNG/WebP/BMP URL，每个最多 10 MiB。" }, "video_urls": { "maxItems": 1, "type": "array", "items": { "type": "string", "format": "uri" }, "description": "仅简单模式，最多 1 个公开 MP4/MOV/WebM URL，最多 100 MiB、241 秒。" }, "audio_urls": { "maxItems": 10, "type": "array", "items": { "type": "string", "format": "uri" }, "description": "简单模式参考音频 URL，每个 6–1800 秒、最多 500 MiB；含风格和歌词在内的总附件数量须为 1–10。" } }, "required": [ "model", "custom_mode", "instrumental" ], "additionalProperties": false } ``` ## 重要条件 * 自定义模式须填写非空title，以及style、lyrics、negative\_tags中至少一项非空内容。必须省略image\_urls、video\_urls和audio\_urls，空数组也不接受。persona\_model须搭配persona\_id。 * 简单模式须有1–10个附件，每个图片/视频/音频URL及非空style、lyrics各计一个；仅prompt不足。必须省略五个控制参数和duration。简单模式的prompt描述音乐、lyrics提供歌词，两者同时使用；自定义模式中lyrics优先于prompt。 * 参考音频每个6–1800秒、最多500 MiB；图片为JPEG/PNG/WebP/BMP，每个最多10 MiB；视频为MP4/MOV/WebM，最多100 MiB、241秒。audio\_weight仅用于自定义且非纯音乐模式。 * 音频URL必须包含可读且时长大于零的MP3/WAV/FLAC/OGG/M4A/AAC音轨，每个文件最多500 MiB。URL须为可公开读取的HTTPS地址、端口443，不含用户名密码或私网地址，且应持续可访问直到任务结束。 * 歌曲音频可能为MP3或M4A；需要真正MP3时使用suno\_export\_mp3。可选封面无法获取时可能为null，不影响音频使用。 * 上传文件保留24小时，生成文件保留14天，任务详情保留30天；复用文件沿用原到期时间。有效Voice/Persona身份映射与任务日志清理分开处理，请及时下载需长期保存的文件。 ## 结果 Schema 创建响应为 \{code:200,msg:"success",data:\{task\_id}}，轮询 GET /api/v1/tasks/\{task\_id}。成功时 data.result 为符合下方 Schema 的对象，其他状态为 null；input 仍为 JSON 字符串。 ```json theme={null} { "type": "object", "required": [ "code", "msg", "data" ], "properties": { "code": { "const": 200 }, "msg": { "type": "string" }, "data": { "type": "object", "required": [ "callbackType", "task_id", "data" ], "properties": { "callbackType": { "const": "complete" }, "task_id": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "audio_url", "stream_audio_url", "image_url", "prompt", "lyrics", "model_name", "title", "createTime", "duration", "tags", "source_audio_url", "source_image_url", "source_stream_audio_url" ], "properties": { "id": { "type": "string" }, "audio_url": { "type": "string" }, "stream_audio_url": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "prompt": { "type": "string" }, "lyrics": { "type": [ "string", "null" ] }, "model_name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "createTime": { "type": [ "integer", "null" ] }, "duration": { "type": [ "number", "null" ] }, "tags": { "type": [ "string", "null" ] }, "source_audio_url": { "type": "string" }, "source_image_url": { "type": [ "string", "null" ] }, "source_stream_audio_url": { "type": [ "string", "null" ] } } } } } } } } ``` > 歌曲duration单位为秒，任务duration单位为毫秒；createTime是毫秒Unix时间戳或null。目前stream\_audio\_url和source\_stream\_audio\_url均为null；source\_audio\_url/source\_image\_url与audio\_url/image\_url指向同一本站托管副本，并非供应商直链。请遍历实际歌曲数组，注册上传音频不代表新生成两首歌曲。 ## 相关流程 [Voice 完整四步](https://docs.apistable.com/zh/suno-voice-workflow.md) [文件上传](https://docs.apistable.com/zh/file-upload.md) [回调](https://docs.apistable.com/zh/webhooks.md) ## OpenAPI ````yaml openapi-suno-generate-zh.json POST /api/v1/tasks/create_task openapi: 3.1.0 info: title: APIstable API version: 1.0.0-preview description: >- Public /api/v1 protocol. Valid API keys have the same account-scoped access. No client submission idempotency or max_credits. Enabled Suno operations use PayAPI and durable task processing. Media uses R2: uploads 24 hours, generated files 14 days, task logs 30 days. Music credit deduction is disabled. Unconfigured operations and LLM return 503. servers: - url: https://apistable.com description: APIstable API security: [] paths: /api/v1/tasks/create_task: post: summary: 生成音乐 description: 写下想表达的内容，用风格或参考素材确定方向；自定义模式可以直接填写歌词。 operationId: suno_generate requestBody: required: true content: application/json: schema: type: object required: - model - input additionalProperties: false properties: model: type: string enum: - suno_generate example: suno_generate input: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: lyrics: type: string maxLength: 5000 description: 最多5000字符。自定义模式传入时优先于prompt；简单模式与prompt同时使用，非空歌词计为一个附件。 prompt: type: string maxLength: 5000 description: >- 简单模式：最多3000字符的描述，与lyrics同时使用。自定义模式：最多5000字符的备用歌词，仅省略lyrics时使用。 style: type: string maxLength: 1000 description: 音乐风格，最多 1000 字符；简单生成时计为一个附件。 negative_tags: type: string maxLength: 1000 description: 排除的风格；增加伴奏或人声时必填。 vocal_gender: type: string enum: - m - f description: m 或 f，表示人声倾向，不保证特定声音身份；生成时仅限自定义模式。 style_weight: type: number minimum: 0 maximum: 1 description: 风格影响程度，0–1，最多两位小数；生成时仅限自定义模式。 weirdness_constraint: type: number minimum: 0 maximum: 1 description: 创意约束，0–1，最多两位小数；生成时仅限自定义模式。 audio_weight: type: number minimum: 0 maximum: 1 description: 音频影响程度，0–1，最多两位小数；生成时仅限自定义且非纯音乐模式。 variety: type: integer minimum: 0 maximum: 4 description: 多样性，0–4 整数，自定义生成默认 1。 persona_id: type: string minLength: 1 maxLength: 200 description: 本站 Voice 或 Persona ID；供应商 root 和原曲映射由后台处理。 persona_model: type: string enum: - style_persona - voice_persona description: style_persona 或 voice_persona，须与资源真实来源匹配。 max_mode: default: false type: boolean description: PayAPI 扩展；Max 模式可能增加上游费用。本站积分扣除当前未启用。 model: type: string enum: - V6 - V6_MINI - V6_WILD description: Suno 版本：V6、V6_MINI 或 V6_WILD；续写需与生成原曲版本一致。 custom_mode: type: boolean description: 自定义模式使用标题、歌词和风格；简单模式使用描述与参考附件。 instrumental: type: boolean description: 生成纯音乐；纯音乐续写不传 prompt、lyrics 和 vocal_gender。 title: type: string maxLength: 80 description: 标题。生成/翻唱最多 80 字符，续写及其他操作最多 100 字符；自定义生成必填。 duration: type: number minimum: 10 maximum: 360 description: 期望时长 10–360 秒；仅自定义生成，省略时自动决定。 image_urls: maxItems: 5 type: array items: type: string format: uri description: 仅简单模式，最多 5 个公开 JPEG/PNG/WebP/BMP URL，每个最多 10 MiB。 video_urls: maxItems: 1 type: array items: type: string format: uri description: 仅简单模式，最多 1 个公开 MP4/MOV/WebM URL，最多 100 MiB、241 秒。 audio_urls: maxItems: 10 type: array items: type: string format: uri description: >- 简单模式参考音频 URL，每个 6–1800 秒、最多 500 MiB；含风格和歌词在内的总附件数量须为 1–10。 required: - model - custom_mode - instrumental additionalProperties: false callback_url: type: string format: uri description: >- Optional public HTTPS endpoint for signed completion callbacks; no redirects or private IPs. example: model: suno_generate input: model: V6 custom_mode: true instrumental: false title: Paper boats at dawn style: Fingerpicked guitar, gentle brushed drums lyrics: |- [Verse] We fold a map into a boat And let the morning carry it home responses: '200': description: Accepted task. Poll the common task endpoint or use callback_url. content: application/json: schema: type: object required: - code - msg - data additionalProperties: false properties: code: const: 200 msg: const: success data: type: object required: - task_id additionalProperties: false properties: task_id: type: string '400': description: >- 40001 invalid JSON, 40002 invalid input/callback, 40003 unsupported parameter. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Invalid or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: '40201: Insufficient credits (live acceptance).' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '40401: Unknown model or resource not found in this account.' content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: '40901: Resource belongs to a different provider account.' content: application/json: schema: $ref: '#/components/schemas/Error' '410': description: '41001: Source audio or temporary resource has expired.' content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: '41301: Request too large.' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: '42201: Requested music combination is not enabled.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '42901: Rate/concurrency limit (live acceptance).' content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: '50301: Service/provider unavailable. No live submission or charge.' content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: Error: type: object required: - code - msg - data properties: code: type: integer msg: type: string data: type: 'null' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Every valid key can submit and query its own account. Revoked keys are rejected. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.