> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/developers/ai-and-music/suno-generation-and-callback-lifecycle.md). # Suno generation & callback lifecycle Suno provider execution, model responsibility, callback ordering, polling, normalized music assets, credits and token-funded generation boundaries. **Status:** `MVP / Preview` unless the owning API operation is explicitly marked `Live` or `Verified`. The current MVP music-generation execution layer is primarily **Suno**. SONIC owns the durable operation, authorization, AI Credit accounting, normalized assets, project state and settlement semantics around the provider. ## Provider responsibility Suno is the **music execution provider** for this integration. Sonic AI or OpenAI may prepare/refine the text brief beforehand, but that does not change the identity of the audio-generation provider. ``` original brief → optional reasoning/text refinement → GenerationOperation → Suno dispatch → Suno job/track evidence → SONIC reconciliation → normalized SongAsset ``` ## Core identity rule Provider task IDs are integration identifiers, not platform business identities. ``` GenerationOperation ├─ original/refined brief snapshot ├─ requested settings ├─ providerJobId? ├─ CreditReservation? ├─ CallbackReceipt[] ├─ ProviderObservation[] ├─ SongAsset[] └─ normalized terminal result ``` ## Dispatch preconditions Before Suno receives a generation request: * signed-session authority is valid; * generation permission/entitlement checks pass; * input schema is valid; * remote upload/cover URLs pass public-network validation; * requested duration/settings are policy-valid; * a durable idempotent `GenerationOperation` exists; * required AI Credits are reserved successfully. A failed reservation means no provider dispatch. ## Ambiguous dispatch handling If the server times out while dispatching, the operation must enter an ambiguous/reconciliation state instead of immediately creating a second provider job. ``` dispatch → timeout / unknown response → recover provider correlation if possible → poll/reconcile → redispatch only when duplicate execution is ruled out ``` ## Callback merge strategy 1. Authenticate/validate the callback using the configured provider strategy. 2. Resolve the internal operation through provider correlation. 3. Persist a callback receipt for audit and replay protection. 4. Resolve stable track identity. 5. Compare incoming stage/completeness with stored state. 6. Merge only fields that add information. 7. Never replace a non-empty completed track field with an earlier/null value. 8. Lock terminal operation state according to the canonical state machine. 9. Apply the terminal AI Credit transition exactly once after normalized result validation. A stale callback can be retained as evidence without regressing authoritative state. ## Poll fallback Record-info polling is a recovery mechanism, not a second lifecycle. ``` callback observation ─┐ ├→ canonical merge/reconcile function poll observation ─────┘ ``` A terminal poll result follows the same validation and settlement path as a callback so callback/poll races cannot double-charge or double-release credits. ## Partial tracks Music providers may return tracks independently. Merge results by stable provider track identity and persist partial progress without treating the overall operation as completed until the owning completion policy is satisfied. A later callback may enrich artwork, audio URL, duration or metadata, but cannot erase a previously validated non-null value with an earlier/null field. ## Duration normalization Store requested and provider-confirmed duration separately: ``` requestedDurationSeconds providerDurationSeconds? ``` The Studio displays provider-confirmed duration for completed assets. Client elapsed time is not authoritative duration metadata. ## Asset normalization and provenance A normalized generated asset should retain safe provenance: ``` operationId provider = "Suno" providerJobId providerTrackId providerModelDisplayName? requestedDurationSeconds providerDurationSeconds? refinementApplied refinementProvider? sourceAssetIds? contentHash? createdAt ``` Provider credentials, secret request headers and internal reconciliation payloads remain server-only. ## Credit-funded generation Every asynchronous AI Credit-funded operation uses: ``` reserve → dispatch → callback/poll reconciliation → validate normalized result → settle | release ``` Completion settles once. Terminal provider failure/cancellation releases once. Financial retry never redispatches provider work. ## SONIC token-funded generation Where explicitly enabled and verified, token-funded generation inserts a separate financial transaction pipeline before provider dispatch: ``` create authoritative TransactionIntent → explicit wallet signature → submit → chain confirmation → effect verification → settlement/reconciliation → consume payment intent once → create/dispatch GenerationOperation ``` Wallet connection is not authentication or transaction authorization. A submitted Solana signature is not settlement. Provider submission is blocked until the required payment state is reconciled. SONIC mint, treasury, decimals and atomic generation amount remain deployment facts and must be verified before production use. ## Song asset tokenization A completed generated track may later be prepared for tokenization where the feature is explicitly enabled. Tokenization is a **new** transaction intent and separate authority boundary. The asset's token mint remains unset until trusted chain reconciliation verifies the resulting on-chain mint and expected authority/state. ## Provider endpoint mapping Provider endpoint names are implementation details and may evolve with the provider adapter. Current integration documentation includes music generation/record-info, lyrics, Upload & Cover, stem separation and WAV conversion. SONIC-facing clients should prefer normalized SONIC APIs rather than calling provider endpoints directly. ## Account-level Suno key Where account-managed provider credentials are supported, a creator may configure a Suno API key through protected Settings. The raw secret is accepted server-side, encrypted/secret-managed, and must not be returned to client JavaScript after persistence. Account-level provider credentials authorize provider API access only. They do not authenticate the SONIC user, grant roles or authorize wallet transactions. ## Provider invariant ``` server-authorized generation + durable SONIC operation + reserved credits/payment state + explicit Suno provider execution + callback/poll convergence + normalized track provenance + exactly-once financial transition = valid Suno-backed SONIC generation ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/developers/ai-and-music/suno-generation-and-callback-lifecycle.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.