v0.5.2 — fix generation against new /api/generate/v2-web/ endpoint

Suno migrated their generation endpoint server-side: `/api/generate/v2/`
now returns `Token validation failed.` for everything, while the live
web app posts to `/api/generate/v2-web/` with a substantially extended
body schema. Captured the new request shape from a real browser session,
ported the CLI to match, and end-to-end verified generate → wait →
download → MP3 with embedded ID3/lyrics tags.

API changes
- POST `/api/generate/v2-web/` (was `/api/generate/v2/`)
- New required body: `negative_tags` (empty string default),
  `user_uploaded_images_b64`, `metadata.{web_client_pathname,
  is_max_mode, is_mumble, create_mode, user_tier, create_session_token,
  disable_volume_normalization}`, `override_fields`, `cover_start_s`,
  `cover_end_s`, `artist_clip_id`, `artist_start_s`, `artist_end_s`,
  `continued_aligned_prompt`, `transaction_uuid`
- `gpt_description_prompt` and `task` fields are gone — describe mode
  now uses `create_mode: "inspiration"` with the prompt in the same
  `prompt` field as custom mode
- `create_session_token` and `transaction_uuid` are random UUIDs per
  request (verified server-side does not validate them)
- `user_tier` is also not validated server-side (verified with empty
  string and arbitrary text — both succeed) so we send empty string

JWT staleness fix
- Suno's generation endpoint silently rejects JWTs older than ~30 min
  with `Token validation failed.` even when the JWT's own `exp` claim
  says it's still valid. Auto-refresh threshold widened from 30s to
  30min so every cold-start command lands with a fresh token.
- `Token validation failed` body pattern now maps to `CliError::AuthExpired`
  so the user gets the right hint instead of an opaque API dump.

Separate `suno credits` fix
- `RemasterModelInfo.can_use` is missing from billing/info responses
  in the wild — added `#[serde(default)]` so deserialization stops
  failing with "error decoding response body".

New `suno update` command
- Self-update from GitHub Releases via the `self_update` crate, ported
  from the agent-cli-framework reference implementation.
- `suno update --check` (peek) and `suno update` (install) both return
  the standard JSON envelope. Added to agent-info commands list.

Schema-drift error mapper
- `check_response()` now detects pydantic-style `loc: ['body','params'…]`
  failures and returns `CliError::Api { code: "schema_drift" }` with a
  suggestion to run `suno update`. Future schema changes will surface
  the right action automatically.

Cover / remaster (best-effort port)
- Both still route through `/api/generate/v2-web/` but with `cover_clip_id`
  set instead of the legacy `task: "cover"` field. NOT verified against
  the real web app — separate captures still needed for those flows.

Cleanup
- Removed the dead `check_captcha()` helper. Its field-name check
  (`captcha_required`) was wrong anyway — Suno's `/api/c/check` returns
  `{"required": ...}`, not `{"captcha_required": ...}`, so the warning
  it gated never fired.

README + SKILL.md updated to mention `suno update` and the new endpoint.
Codex review (gpt-5.4 xhigh) approved the patch with two notes that have
been addressed (captcha helper removed cleanly, schema_drift mapper added).

Verified end-to-end:
- `suno credits` → success JSON
- `suno generate --instrumental --wait --download` → 2 complete MP3s
- `suno generate --lyrics-file --wait --download` → 2 complete MP3s
  with prompt embedded in metadata
- `suno info`, `suno list`, `suno models`, `suno agent-info` → success
- `suno update --check` → reports current 0.5.2 vs latest 0.5.1

Author: longevityboris

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "suno"
-version = "0.5.1"
+version = "0.5.2"
 edition = "2024"
 description = "Generate AI music from your terminal — Suno v5.5 with tags, exclude, vocal control, and all generation features"
 license = "MIT"
@@ -30,6 +30,7 @@ futures-util = "0.3"
 id3 = "1"
 rookie = "0.5"
 uuid = { version = "1", features = ["v4"] }
+self_update = { version = "0.42", default-features = false, features = ["rustls", "compression-flate2", "archive-tar"] }
 
 [dev-dependencies]
 assert_cmd = "2"

Cargo.toml

@@ -53,6 +53,17 @@ cargo install suno
 
 Download from [GitHub Releases](https://github.com/199-biotechnologies/suno-cli/releases) — binaries for macOS (Apple Silicon + Intel), Linux (x86_64 + ARM), and Windows.
 
+### Self-update
+
+Already have `suno` installed? Pull the latest binary from GitHub Releases without touching your package manager:
+
+```bash
+suno update --check    # see what's available
+suno update            # install the latest release
+```
+
+> Tip: when Suno changes their API mid-cycle, run `suno update` first — it's faster than `cargo install suno` or waiting for the Homebrew bottle to refresh.
+
 ## Quick Start
 
 ```bash
@@ -128,6 +139,7 @@ suno auth            Set up authentication
 suno config          show | set | check
 suno agent-info      Machine-readable capabilities JSON
 suno install-skill   Install agent skill into Claude Code / Cursor
+suno update          Self-update from GitHub Releases (--check to peek first)
 ```
 
 ## Features
@@ -191,7 +203,7 @@ suno cover <clip_id> --tags "jazz, smooth piano" --model v5.5 --wait
 suno remaster <clip_id> --model v5.5 --wait --download ./remastered/
 ```
 
-Both route through Suno's unified generation endpoint (`/api/generate/v2/`).
+Both route through Suno's unified web generation endpoint (`/api/generate/v2-web/`).
 
 ### Clip Info
 

README.md

@@ -185,5 +185,6 @@ suno download $ids --output ./archive/
 
 - Auth refreshes automatically (~7-day session lifetime).
 - Captcha is **not** required for Premier accounts with 200+ credits consumed.
-- All generation paths (normal, voice persona, cover, extend) go through `/api/generate/v2/` with different `task` values — but you don't need to know that, just use the subcommands.
+- All generation paths (normal, voice persona, cover, extend) go through `/api/generate/v2-web/` — but you don't need to know that, just use the subcommands.
+- When the CLI returns `schema_drift` (Suno changed their API), run `suno update` to pull the latest binary from GitHub Releases.
 - When unsure about flags, run `suno <command> --help` or `suno agent-info`.

assets/SKILL.md

@@ -4,30 +4,20 @@ use crate::errors::CliError;
 
 impl SunoClient {
     /// Create a cover of an existing clip.
-    /// Routes through /api/generate/v2/ with task="cover" + cover_clip_id.
+    /// Posts to `/api/generate/v2-web/` with `cover_clip_id` set. The legacy
+    /// `task: "cover"` field is gone in v2-web; we still don't have a fresh
+    /// web-app capture for the cover flow, so this is a best-guess port — if
+    /// the API rejects, we'll need to capture a real cover request and add
+    /// any missing required fields (e.g. cover_start_s/cover_end_s).
     pub async fn cover(
         &self,
         clip_id: &str,
         model_key: &str,
         tags: Option<&str>,
     ) -> Result<Vec<Clip>, CliError> {
-        let req = GenerateRequest {
-            mv: model_key.to_string(),
-            prompt: None,
-            gpt_description_prompt: None,
-            title: None,
-            tags: tags.map(String::from),
-            negative_tags: None,
-            make_instrumental: false,
-            generation_type: None,
-            token: None,
-            continue_clip_id: None,
-            continue_at: None,
-            task: Some("cover".into()),
-            persona_id: None,
-            cover_clip_id: Some(clip_id.to_string()),
-            metadata: None,
-        };
+        let mut req = GenerateRequest::new(model_key, "cover");
+        req.tags = tags.map(String::from);
+        req.cover_clip_id = Some(clip_id.to_string());
         self.generate(&req).await
     }
 }

src/api/cover.rs

@@ -4,8 +4,11 @@ use crate::errors::CliError;
 
 impl SunoClient {
     /// Submit a music generation request (custom mode or inspiration mode).
+    /// Posts to `/api/generate/v2-web/` — the legacy `/api/generate/v2/`
+    /// returns `Token validation failed` since Suno migrated creates to
+    /// `v2-web` server-side (verified 2026-04-07).
     pub async fn generate(&self, req: &GenerateRequest) -> Result<Vec<Clip>, CliError> {
-        let resp = self.post("/api/generate/v2/").json(req).send().await?;
+        let resp = self.post("/api/generate/v2-web/").json(req).send().await?;
         let resp = self.check_response(resp).await?;
         let result: GenerateResponse = resp.json().await?;
         Ok(result.clips)

src/api/generate.rs

@@ -47,20 +47,4 @@ impl SunoClient {
         })?;
         Ok(serde_json::from_value(words.clone())?)
     }
-
-    /// Check whether captcha is required before generation.
-    pub async fn check_captcha(&self) -> Result<bool, CliError> {
-        let resp = self
-            .post("/api/c/check")
-            .json(&serde_json::json!({"ctype": "generation"}))
-            .send()
-            .await?;
-        let resp = self.check_response(resp).await?;
-        // Try to parse; if the response doesn't have captcha_required, assume false
-        let body: serde_json::Value = resp.json().await?;
-        Ok(body
-            .get("captcha_required")
-            .and_then(|v| v.as_bool())
-            .unwrap_or(false))
-    }
 }

src/api/metadata.rs

@@ -111,6 +111,26 @@ impl SunoClient {
         }
         if !status.is_success() {
             let body = resp.text().await.unwrap_or_default();
+            // Map known Suno error patterns to actionable codes so callers
+            // get a meaningful suggestion instead of an opaque HTTP dump.
+            //
+            // `Token validation failed` is what Suno returns when the JWT
+            // has crossed their server-side staleness threshold (~30 min)
+            // even when the JWT's own `exp` claim is still valid. We treat
+            // it as `AuthExpired` so the next CLI invocation will refresh
+            // via the Clerk session cookie and pick up a fresh token.
+            if body.contains("Token validation failed") {
+                return Err(CliError::AuthExpired);
+            }
+            if body.contains("'loc': ['body', 'params'") || body.contains("\"loc\": [\"body\", \"params\"")
+            {
+                return Err(CliError::Api {
+                    code: "schema_drift",
+                    message: format!(
+                        "HTTP {status}: Suno's request schema has changed — the CLI needs an update. Body: {body}"
+                    ),
+                });
+            }
             return Err(CliError::Api {
                 code: "api_error",
                 message: format!("HTTP {status}: {body}"),

src/api/mod.rs

@@ -4,30 +4,16 @@ use crate::errors::CliError;
 
 impl SunoClient {
     /// Remaster a clip with a different model version.
-    /// Routes through /api/generate/v2/ with the remaster model key
-    /// and cover_clip_id pointing to the original.
+    /// Posts to `/api/generate/v2-web/` with the remaster model key and
+    /// `cover_clip_id` pointing to the original. As with `cover()`, this is
+    /// a best-guess port pending a real captured remaster request.
     pub async fn remaster(
         &self,
         clip_id: &str,
         remaster_model_key: &str,
     ) -> Result<Vec<Clip>, CliError> {
-        let req = GenerateRequest {
-            mv: remaster_model_key.to_string(),
-            prompt: None,
-            gpt_description_prompt: None,
-            title: None,
-            tags: None,
-            negative_tags: None,
-            make_instrumental: false,
-            generation_type: None,
-            token: None,
-            continue_clip_id: None,
-            continue_at: None,
-            task: Some("cover".into()),
-            persona_id: None,
-            cover_clip_id: Some(clip_id.to_string()),
-            metadata: None,
-        };
+        let mut req = GenerateRequest::new(remaster_model_key, "remaster");
+        req.cover_clip_id = Some(clip_id.to_string());
         self.generate(&req).await
     }
 }

src/api/remaster.rs

@@ -60,6 +60,9 @@ pub struct RemasterModelInfo {
     pub name: String,
     pub external_key: String,
     pub is_default_model: bool,
+    /// Suno's billing/info response for remaster models does NOT include this
+    /// field — keep it optional so deserialization succeeds.
+    #[serde(default)]
     pub can_use: bool,
 }
 
@@ -142,48 +145,113 @@ pub struct FilterPresence {
 }
 
 // --- Generation ---
+//
+// Schema captured from a real Suno web-app POST to `/api/generate/v2-web/`
+// on 2026-04-07 (see API_INTELLIGENCE.md). The old `/api/generate/v2/` path
+// returns `Token validation failed` since Suno started routing creates
+// through `v2-web` exclusively. Most of the new `null` fields are pure
+// placeholders the web app sends regardless of mode — they MUST be present
+// or pydantic returns `missing field`.
 
 #[derive(Debug, Serialize)]
 pub struct GenerateRequest {
-    pub mv: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub prompt: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub gpt_description_prompt: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
+    /// Captcha/anti-bot token. Always serialized as `null` from the CLI; the
+    /// real validation happens via `metadata.create_session_token`.
+    pub token: Option<String>,
+    pub generation_type: String,
     pub title: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
     pub tags: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub negative_tags: Option<String>,
+    /// Always present, defaults to "" (empty string, NOT null).
+    pub negative_tags: String,
+    pub mv: String,
+    pub prompt: String,
     pub make_instrumental: bool,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub generation_type: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub token: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
+    pub user_uploaded_images_b64: Option<String>,
+    pub metadata: GenerateMetadata,
+    /// Always present, empty array unless overriding model fields.
+    pub override_fields: Vec<serde_json::Value>,
+    pub cover_clip_id: Option<String>,
+    pub cover_start_s: Option<f64>,
+    pub cover_end_s: Option<f64>,
+    pub persona_id: Option<String>,
+    pub artist_clip_id: Option<String>,
+    pub artist_start_s: Option<f64>,
+    pub artist_end_s: Option<f64>,
     pub continue_clip_id: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
+    pub continued_aligned_prompt: Option<String>,
     pub continue_at: Option<f64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub task: Option<String>,
-    /// Voice persona ID — used with task="vox"
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub persona_id: Option<String>,
-    /// Source clip for covers/remasters — used with task="cover"
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub cover_clip_id: Option<String>,
-    /// Control sliders — nested correctly under metadata per xiliourt/Suno-Architect
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub metadata: Option<GenerateMetadata>,
+    /// Random UUID generated per request — required.
+    pub transaction_uuid: String,
+}
+
+impl GenerateRequest {
+    /// Build a `GenerateRequest` with all the new-schema placeholder fields
+    /// pre-populated (nulls, empty arrays, fresh UUIDs). Callers only need to
+    /// override the fields that matter for their command.
+    pub fn new(mv: &str, create_mode: &str) -> Self {
+        Self {
+            token: None,
+            generation_type: "TEXT".to_string(),
+            title: None,
+            tags: None,
+            negative_tags: String::new(),
+            mv: mv.to_string(),
+            prompt: String::new(),
+            make_instrumental: false,
+            user_uploaded_images_b64: None,
+            metadata: GenerateMetadata::new(create_mode),
+            override_fields: Vec::new(),
+            cover_clip_id: None,
+            cover_start_s: None,
+            cover_end_s: None,
+            persona_id: None,
+            artist_clip_id: None,
+            artist_start_s: None,
+            artist_end_s: None,
+            continue_clip_id: None,
+            continued_aligned_prompt: None,
+            continue_at: None,
+            transaction_uuid: uuid::Uuid::new_v4().to_string(),
+        }
+    }
 }
 
+/// Web-app metadata block. All fields are required by the new schema even if
+/// they're decorative. `user_tier` is NOT validated server-side (verified with
+/// empty string and arbitrary text — both succeed).
 #[derive(Debug, Serialize)]
 pub struct GenerateMetadata {
+    pub web_client_pathname: String,
+    pub is_max_mode: bool,
+    pub is_mumble: bool,
+    pub create_mode: String,
+    pub user_tier: String,
+    /// Random UUID generated per request — looks decorative but must be present.
+    pub create_session_token: String,
+    pub disable_volume_normalization: bool,
+    /// Control sliders (weirdness / style influence). Optional — only sent
+    /// when --weirdness or --style-influence is passed.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub control_sliders: Option<ControlSliders>,
 }
 
+impl GenerateMetadata {
+    /// Build a metadata block with default web-app values + a fresh session
+    /// token. This matches what the real Suno UI sends per generation.
+    pub fn new(create_mode: &str) -> Self {
+        Self {
+            web_client_pathname: "/create".to_string(),
+            is_max_mode: false,
+            is_mumble: false,
+            create_mode: create_mode.to_string(),
+            user_tier: String::new(),
+            create_session_token: uuid::Uuid::new_v4().to_string(),
+            disable_volume_normalization: false,
+            control_sliders: None,
+        }
+    }
+}
+
 #[derive(Debug, Serialize)]
 pub struct ControlSliders {
     /// Weirdness: 0.0-1.0 (maps from 0-100 in UI)