{"openapi":"3.1.0","info":{"title":"Suno API","version":"0.1.0","description":"A clean, production-grade HTTP API for AI music generation. Async jobs, webhooks, idempotency, and pluggable engines."},"servers":[{"url":"https://api.studioheat.io","description":"This instance"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key, sent as `Authorization: Bearer <key>`."}},"schemas":{"Model":{"type":"string","enum":["bark-v1","bark-v2","chirp-v3"],"description":"Generation model. Higher versions trade speed for fidelity.","example":"chirp-v3"},"Clip":{"type":"object","properties":{"id":{"type":"string","example":"clip_8f3c…"},"audioUrl":{"type":"string","format":"uri","example":"https://api.sunoapi.dev/v1/assets/clip_8f3c.mp3"},"streamUrl":{"type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"durationSeconds":{"type":"number","example":142}},"required":["id","audioUrl","streamUrl","imageUrl","durationSeconds"]},"SongError":{"type":["object","null"],"properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["type","code","message"]},"Song":{"type":"object","properties":{"id":{"type":"string","example":"song_2a9f…"},"object":{"type":"string","enum":["song"]},"status":{"type":"string","enum":["queued","processing","succeeded","failed"],"example":"succeeded"},"model":{"$ref":"#/components/schemas/Model"},"prompt":{"type":"string"},"lyrics":{"type":["string","null"]},"style":{"type":["string","null"],"example":"lo-fi hip hop, mellow, rainy night"},"title":{"type":["string","null"]},"instrumental":{"type":"boolean"},"progress":{"type":"number","minimum":0,"maximum":100,"example":100},"clips":{"type":"array","items":{"$ref":"#/components/schemas/Clip"}},"error":{"$ref":"#/components/schemas/SongError"},"callbackUrl":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"createdAt":{"type":"string"},"completedAt":{"type":["string","null"]}},"required":["id","object","status","model","prompt","lyrics","style","title","instrumental","progress","clips","error","callbackUrl","metadata","createdAt","completedAt"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"invalid_request_error"},"code":{"type":"string","example":"missing_prompt"},"message":{"type":"string","example":"A prompt is required unless lyrics are provided."},"request_id":{"type":"string","example":"req_2a9f…"}},"required":["type","code","message","request_id"]}},"required":["error"]},"CreateSongRequest":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":2000,"example":"an upbeat synthwave anthem about shipping software at 2am"},"lyrics":{"type":"string","maxLength":5000,"description":"Provide your own lyrics, or omit to auto-write them."},"style":{"type":"string","maxLength":500,"example":"synthwave, driving, retro, 120bpm"},"title":{"type":"string","maxLength":120},"instrumental":{"type":"boolean","default":false},"model":{"allOf":[{"$ref":"#/components/schemas/Model"},{"default":"chirp-v3"}]},"callbackUrl":{"type":"string","format":"uri","description":"We POST the finished song here when generation completes."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key/value tags echoed back on the song."}}},"SongList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Song"}},"nextCursor":{"type":["string","null"]}},"required":["object","data","nextCursor"]},"Lyrics":{"type":"object","properties":{"object":{"type":"string","enum":["lyrics"]},"title":{"type":"string"},"lyrics":{"type":"string"}},"required":["object","title","lyrics"]},"CreateLyricsRequest":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":2000,"example":"a breakup song set in a diner at closing time"},"style":{"type":"string","maxLength":500}},"required":["prompt"]}},"parameters":{}},"paths":{"/v1/songs":{"post":{"tags":["Songs"],"summary":"Create a song","description":"Starts an asynchronous generation and returns the song in `queued` state. Poll `GET /songs/{id}` or supply a `callbackUrl` to receive a webhook on completion. Pass an `Idempotency-Key` header to safely retry.","parameters":[{"schema":{"type":"string","description":"Retry-safe unique key."},"required":false,"name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSongRequest"}}}},"responses":{"202":{"description":"Generation accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Song"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Songs"],"summary":"List songs","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pass the previous response's nextCursor."},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"A page of songs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SongList"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/songs/{id}":{"get":{"tags":["Songs"],"summary":"Retrieve a song","parameters":[{"schema":{"type":"string","example":"song_2a9f…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The song","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Song"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/lyrics":{"post":{"tags":["Lyrics"],"summary":"Generate lyrics","description":"Synchronously writes lyrics from a prompt. Feed the result into `POST /songs` as `lyrics`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLyricsRequest"}}}},"responses":{"200":{"description":"Generated lyrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lyrics"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}