Migrating from gcui-art/suno-api to a hosted Suno API
Updated 2026-07-10
The self-hosted era of gcui-art/suno-api is winding down. The project (3k+ stars, the default way to call Suno from code for two years) is effectively unmaintained: in December 2025 its author opened an issue asking “is anyone out there willing to take over this project?”, and the CAPTCHA flow has been broken against Suno’s v5.5 UI for months — /api/custom_generate hangs on waiting for locator('.custom-textarea') until it times out. If you’re here because your wrapper just died, this guide is the 15-minute exit: Tunova keeps the same endpoint names for the calls that matter, so the migration is a base URL and a header.
Why the wrapper keeps breaking
The wrapper drives Suno’s consumer web app with browser automation: your cookie, a paid CAPTCHA-solver balance, and CSS selectors into Suno’s UI. Every Suno frontend change is a potential outage that waits for a maintainer patch — and there is currently no maintainer. That’s not a knock on the project (it was great to prototype with — we’ve written warmly about it); it’s the structural cost of self-hosting a moving target. A managed API absorbs that risk for you and puts an SLA-shaped contract — stable REST, request ids, honest billing — between your app and the churn.
Endpoint mapping (mostly: keep the name)
| gcui-art/suno-api (self-hosted) | Tunova |
|---|---|
Auth: SUNO_COOKIE env + CAPTCHA solver key | one header — X-API-Key: sk_live_… |
POST /api/generate (description mode) | POST /api/generate — same name; body {prompt, model?, make_instrumental?, callback_url?} → 202 {job_id} |
POST /api/custom_generate (your lyrics/tags/title) | POST /api/custom_generate — same name; {prompt: lyrics, tags, title, …} |
POST /api/generate_lyrics | POST /api/lyrics — {prompt} (2 tokens) |
GET /api/get?ids=… (poll clips) | GET /api/jobs/{id} → {status, clips:[{audio_url, duration}]} |
wait_audio: true (blocking mode) | pass callback_url → HMAC-signed webhook on completion (or poll) |
GET /api/get_limit (quota) | GET /api/me → {token_balance, song_cost, lyrics_cost} |
/api/extend_audio, /api/generate_stems, /api/concat, /api/get_aligned_lyrics | not supported yet — keep the wrapper for these if you use them (honest answer; see FAQ) |
What actually changes (all of it in your favor)
- Delete the ops. No
SUNO_COOKIEto refresh, no 2captcha balance, no Vercel bridge to host, no selector patches when Suno ships UI changes. Your integration becomes two HTTP calls. - Billed only on success. Self-hosting charges your own Suno account credits whether or not the render survives; Tunova auto-refunds a failed render as its own ledger line — you never pay for output you didn’t get.
- Async done right.
202 + job_id, then poll or an HMAC-signed webhook; a retried submit with the sameIdempotency-Keyreturns the same job, so a flaky network can’t double-charge you. - Agent-native. The README pitched “integrate it into agents like GPTs” — Tunova ships that as a hosted MCP server (
generate_song/wait_for_song/check_song), plus OpenAPI andllms.txt. See the MCP guide.
Before / after
Prefer a higher-level call? The zero-dependency Python & Node SDKs wrap submit → wait → audio URL (and verify the webhook) in one function.
Port it in one sitting
Every account starts with 50 free tokens, no card (≈ 5 songs) — enough to port and smoke-test the swap before you top up (crypto; tokens never expire). Models v5.5. See the quickstart (cURL / Python / Node / MCP), or grab a key.
FAQ
Is gcui-art/suno-api still maintained?
Effectively no. In December 2025 the maintainer opened an issue asking if anyone was willing to take over the project, and it has seen no fix for the CAPTCHA breakage reported against Suno's v5.5 UI. The repo (3k+ stars) still works as a reference, but breakage now waits on a volunteer.
Why does /api/custom_generate time out with waiting for locator('.custom-textarea')?
Suno's v5.5 web UI removed the .custom-textarea element that the wrapper's browser automation targets, so the CAPTCHA/submit flow waits forever and times out. Fixing it means patching the automation yourself every time Suno ships a UI change — or moving to a managed API where that's someone else's job.
How hard is the migration to Tunova?
Unusually easy: the two endpoints most integrations call — /api/generate and /api/custom_generate — keep the same names on Tunova. You swap the base URL, add an X-API-Key header, and delete the cookie/CAPTCHA environment. The async shape changes from wait_audio-style polling on clip ids to a job_id you poll (or a signed webhook).
What do I stop paying for?
Your dedicated Suno subscription for the wrapper, the 2captcha (or similar) solver balance, the hosting for the bridge, and the hours of babysitting when Suno changes. Tunova is billed in tokens per successful render only — a failed render auto-refunds, which a self-hosted wrapper can't offer since Suno has already charged your account credits.
Does Tunova support extend_audio, stems, or concat?
Not yet. Tunova covers the core generate paths (prompt mode, custom-lyrics mode, and standalone lyrics generation). If your integration depends on audio extension, stem separation, or clip concatenation, keep the wrapper for those calls and route generation through the API that stays up — or check the changelog, the surface is growing.
Do I need to run a browser or solve CAPTCHAs?
No. That's the point of a managed route: there is no cookie to paste, no browser automation to patch, no CAPTCHA solver to fund. You call a REST endpoint with an API key and get a job id back; Tunova absorbs the operational side and only bills you when a render delivers.
Related guides
- Self-hosting a Suno API: the hidden costs — the full cost model behind this migration.
- The best Suno API in 2026 — self-host vs Kie.ai vs sunoapi.org vs Tunova.
- Is there an official Suno API? — including Suno’s July 2026 partner-program exploration.
- Error handling & webhooks, done right.
Tunova is an independent service, not affiliated with or endorsed by Suno or the gcui-art/suno-api project. “Suno” is a trademark of its owner.