接入文档/音乐/文生图

Suno Music· 文生图

文生图

POSThttps://api.sozdai.ai/v1/media/generations

计费方式

按成功生成的任务计费,详见价格页。

执行流程

异步任务模型:提交后由后台队列生成,轮询获取结果。

#提交任务

媒体生成是异步的：提交后立即返回任务 id，不阻塞等待。

bash

curl https://api.sozdai.ai/v1/media/generations \
  -H "Authorization: Bearer $CORRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "suno-music", "prompt": "calm ambient piano with soft melodies", "instrumental": true }'
# → { "id": "cmus7q0x9000108l3f5g2abcd", "status": "queued" }

#请求参数

参数	类型	必填	默认	说明
`version`	string	否	`V5_5`	Suno 引擎版本（模型是参数，不是单独的接口）。默认 V5_5（最新）。可选值: V5_5, V5, V4_5PLUS, V4_5, V4_5ALL, V4
`prompt`	string	是	—	非自定义模式（默认）：一句创意，歌词自动生成 —— 最多 500 字符。自定义模式（customMode: true）：作为歌词原文 —— V4 最多 3000 字符，其余版本最多 5000。
`customMode`	boolean	否	`false`	高级模式。为 true 时需提供 style、title（非纯音乐时 prompt 作为歌词）。
`instrumental`	boolean	否	`false`	生成纯音乐（无人声）。
`style`	string	否	—	风格/情绪（自定义模式必填）。V4 最多 200 字符，其余版本最多 1000。如 Synthwave、Jazz、Lo-fi。
`title`	string	否	—	曲目标题（自定义模式必填，最长 80 字符）。
`negativeTags`	string	否	—	要规避的风格/特征，如 Heavy Metal。
`vocalGender`	string	否	—	人声性别偏好（仅自定义模式，尽力而为）。可选值: m, f
`styleWeight`	number	否	—	对 style 的遵循强度。范围 0–1，最多两位小数。
`weirdnessConstraint`	number	否	—	实验性/创意偏离程度。范围 0–1，最多两位小数。
`audioWeight`	number	否	—	音频特征相对其它因素的权重。范围 0–1，最多两位小数。
`personaId`	string	否	—	为生成应用 Persona/音色。仅自定义模式。
`personaModel`	string	否	—	Persona 类型。仅 V5 和 V5_5 可用。可选值: style_persona, voice_persona
`callback_url`	string	否	—	可选的公网 http(s) 地址。任务生成完成（成功或失败）后，我们会第一时间把结果 POST 到这里。

#查询任务结果

生成是异步的 —— 提交接口会立即返回一个任务 id。用这个 id 每隔几秒请求下面的接口，直到 status 变为 succeeded（结果就绪）或终止状态（failed / timeout）。

GEThttps://api.sozdai.ai/v1/media/generations/{id}

bash

# take the id from the submit response, then poll every ~3s
curl https://api.sozdai.ai/v1/media/generations/cmus7q0x9000108l3f5g2abcd \
  -H "Authorization: Bearer $CORRY_KEY"
# repeat until "status" is "succeeded" (or "failed" / "timeout")

#响应示例

提交时

json

{
  "id": "cmus7q0x9000108l3f5g2abcd",
  "status": "queued",
  "type": "music",
  "model": "suno-music"
}

成功后（轮询返回）

json

{
  "id": "cmus7q0x9000108l3f5g2abcd",
  "status": "succeeded",
  "type": "music",
  "model": "suno-music",
  "tracks": [
    {
      "id": "cmus7q9p1000208l3h6j3efgh",
      "title": "Paper Sunburn",
      "tags": "pop, upbeat, bright synth, punchy",
      "lyrics": "[Verse 1]\nCity lights on the dashboard glow\n...",
      "duration": 139.92,
      "streamUrl": "https://api.sozdai.ai/v1/media/stream/cmus7q9p1000208l3h6j3efgh/<token>",
      "audioUrl": "https://cdn.sozdai.ai/music/1782583687607-75e9dd8e8b89.mp3",
      "imageUrl": "https://cdn.sozdai.ai/music/cover/1782583641794-896ad6ebb572.jpeg"
    },
    {
      "id": "cmus7qam2000308l3k7m4ijkl",
      "title": "Paper Sunburn",
      "tags": "pop, upbeat, bright synth, punchy",
      "lyrics": "[Verse 1]\nCity lights on the dashboard glow\n...",
      "duration": 176.88,
      "streamUrl": "https://api.sozdai.ai/v1/media/stream/cmus7qam2000308l3k7m4ijkl/<token>",
      "audioUrl": "https://cdn.sozdai.ai/music/1782583693241-bfbcad7cf9d8.mp3",
      "imageUrl": "https://cdn.sozdai.ai/music/cover/1782583648301-bec46f245a73.jpeg"
    }
  ],
  "cost": "0.1200",
  "currency": "USD"
}

响应字段

字段	类型	说明
`status`	string	任务状态：queued / submitted / succeeded / failed / timeout。
`type`	string	媒体类型：image / video / music。
`model`	string	你请求的模型名。
`tracks`	array	生成的音轨（通常 2 条），每个对象含下表字段。
`error`	string	任务失败时的错误信息。
`cost`	string	本次任务扣费金额 —— 美元字符串（如 "0.1200"），配合 currency 字段。
`currency`	string	cost 的货币，恒为 "USD"。

音轨对象

字段	类型	说明
`id`	string	音轨 id（用于 streamUrl）。
`title`	string	曲目标题。
`tags`	string	风格标签，逗号分隔。
`lyrics`	string	歌词；纯音乐为 "[Instrumental]"。
`duration`	number	时长（秒）。
`streamUrl`	string	生成中即可播放；转存后自动指向 CDN 文件。
`audioUrl`	string	最终 mp3（我们的 CDN，完成后出现）。
`imageUrl`	string	封面图（我们的 CDN）。

边生成边听

音轨（含 streamUrl、封面、歌词）在约 20–30s 就会出现，早于整首完成 —— 轮询任务拿到后即可播放 streamUrl。audioUrl（我们 CDN 上的最终 mp3）会在生成完成时补上。