generationIdpath · RequiredSuno Generation identifier returned by song creation.
Minimum characters: 1./api/v1/suno/generations/{generationId}Authentication · x-api-key
Canonical product view for one Suno generation. It exposes every candidate's submitted/queued/streaming/complete/error lifecycle independently. Use GET /api/v1/tasks/{taskId} for execution and billing diagnostics.
generationIdpath · RequiredSuno Generation identifier returned by song creation.
Minimum characters: 1.application/json
Unknown fields are not accepted.
autoFinalizeRequiredbillingRequiredUnknown fields are not accepted.
billing.creditsChargedRequiredMay be null. Must match at least one alternative.
billing.creditsCharged · anyOf 1AlternativeMinimum: 0.
billing.creditsCharged · anyOf 2Alternativebilling.creditsRequiredRequiredMinimum: 0.
billing.pricingRequiredMay be null. Must match at least one alternative.
billing.pricing · anyOf 1AlternativeUnknown fields are not accepted.
billing.pricing · anyOf 1.adjustmentCreditsRequiredchargedCredits - baseCredits
billing.pricing · anyOf 1.baseCreditsRequiredStandard quoted credits before customer pricing adjustment
billing.pricing · anyOf 1.chargedCreditsRequiredFrozen task charge. New whole-credit quotes are integers; historical fractional quotes retain up to four decimal places.
Minimum: 0.
billing.pricing · anyOf 1.quoteVersionRequiredPricing quote version stored with the task
billing.pricing · anyOf 1.sourceRequiredPublic pricing source category
Must match at least one alternative.
billing.pricing · anyOf 1.source · anyOf 1Alternativebilling.pricing · anyOf 1.source · anyOf 1See schemaExpand this value in the interactive reference.
billing.pricing · anyOf 1.source · anyOf 2Alternativebilling.pricing · anyOf 1.source · anyOf 2See schemaExpand this value in the interactive reference.
billing.pricing · anyOf 1.billingIncrementCreditsOptionalSmallest customer charge increment
Minimum: 0.0001.
billing.pricing · anyOf 1.calculatedCreditsOptionalPrecise whole-order subtotal before settlement rounding
billing.pricing · anyOf 1.settlementPolicyVersionOptionalVersioned customer settlement policy
billing.pricing · anyOf 1.settlementRoundingCreditsOptionalWhole-order rounding adjustment added at settlement
Minimum: 0.
billing.pricing · anyOf 2Alternativebilling.refundedRequiredbilling.settlementStatusRequiredclipsRequiredclips[]Each itemUnknown fields are not accepted.
clips[].accessLevelRequiredRead projection only. owned returns the full public Clip contract; shared is public or remixable; external is merely readable by clipId. This value does not grant derive or export permission.
clips[].audioUrlRequiredMay be null. Must match at least one alternative.
clips[].audioUrl · anyOf 1Alternativeclips[].audioUrl · anyOf 2Alternativeclips[].clipIdRequiredSuno clip identifier (`mid`); do not substitute an OmnAPI resource identifier.
clips[].createdAtRequiredMay be null. Must match at least one alternative.
clips[].createdAt · anyOf 1AlternativeFormat: date-time.
clips[].createdAt · anyOf 2Alternativeclips[].deliveryStatusRequiredclips[].durationRequiredMay be null. Must match at least one alternative.
clips[].duration · anyOf 1AlternativeClip duration in seconds. Missing eventually-consistent metadata is repaired on later reads.
Minimum: 0.
clips[].duration · anyOf 2Alternativeclips[].errorCodeRequiredMay be null. Must match at least one alternative.
clips[].errorCode · anyOf 1Alternativeclips[].errorCode · anyOf 2Alternativeclips[].errorMessageRequiredMay be null. Must match at least one alternative.
clips[].errorMessage · anyOf 1Alternativeclips[].errorMessage · anyOf 2Alternativeclips[].imageUrlRequiredMay be null. Must match at least one alternative.
clips[].imageUrl · anyOf 1Alternativeclips[].imageUrl · anyOf 2Alternativeclips[].indexRequiredMinimum: 0.
clips[].instrumentalRequiredMay be null. Must match at least one alternative.
clips[].instrumental · anyOf 1Alternativeclips[].instrumental · anyOf 2Alternativeclips[].majorModelVersionRequiredMay be null. Must match at least one alternative.
clips[].majorModelVersion · anyOf 1AlternativeExact Suno major_model_version value reported for this clip, for example v4.5-all.
clips[].majorModelVersion · anyOf 2Alternativeclips[].modelRequiredMay be null. Must match at least one alternative.
clips[].model · anyOf 1AlternativeCompatibility model label. Prefer modelCode, providerModelName and majorModelVersion for unambiguous integrations.
clips[].model · anyOf 2Alternativeclips[].modelCodeRequiredMay be null. Must match at least one alternative.
clips[].modelCode · anyOf 1AlternativeCanonical OmnAPI model code selected for an owned generation. Null when a clip is read directly from Suno without a local task.
clips[].modelCode · anyOf 2Alternativeclips[].playableRequiredclips[].playbackRequiredUnknown fields are not accepted.
clips[].playback.deliveryRequiredclips[].playback.expiresAtRequiredMay be null. Must match at least one alternative.
clips[].playback.expiresAt · anyOf 1AlternativeFormat: date-time.
clips[].playback.expiresAt · anyOf 1See schemaExpand this value in the interactive reference.
Format: date-time.
clips[].playback.expiresAt · anyOf 2Alternativeclips[].playback.expiresAt · anyOf 2See schemaExpand this value in the interactive reference.
clips[].playback.mimeTypeRequiredMay be null. Must match at least one alternative.
clips[].playback.mimeType · anyOf 1AlternativeMust match at least one alternative.
clips[].playback.mimeType · anyOf 1See schemaExpand this value in the interactive reference.
Must match at least one alternative.
clips[].playback.mimeType · anyOf 2Alternativeclips[].playback.mimeType · anyOf 2See schemaExpand this value in the interactive reference.
clips[].playback.retryAfterMsRequiredMay be null. Must match at least one alternative.
clips[].playback.retryAfterMs · anyOf 1AlternativeMinimum: 0.
clips[].playback.retryAfterMs · anyOf 1See schemaExpand this value in the interactive reference.
Minimum: 0.
clips[].playback.retryAfterMs · anyOf 2Alternativeclips[].playback.retryAfterMs · anyOf 2See schemaExpand this value in the interactive reference.
clips[].playback.seekableRequiredclips[].playback.sessionCreateUrlRequiredMay be null. Must match at least one alternative.
clips[].playback.sessionCreateUrl · anyOf 1AlternativeDeprecated compatibility field. New integrations should use playback.url directly; no separate playback-session request is needed.
Deprecated; omit in new integrations.
clips[].playback.sessionCreateUrl · anyOf 1See schemaExpand this value in the interactive reference.
Deprecated; omit in new integrations.
clips[].playback.sessionCreateUrl · anyOf 2Alternativeclips[].playback.sessionCreateUrl · anyOf 2See schemaExpand this value in the interactive reference.
clips[].playback.stateRequiredclips[].playback.urlRequiredMay be null. Must match at least one alternative.
clips[].playback.url · anyOf 1AlternativeCurrent playback URL. Live Generation reads provide a temporary URL; final reads provide the completed audio URL. Resolve relative URLs against the API base URL and open them without an API key. A null value means to wait and query the Generation again. Treat the complete URL as private and do not construct or modify it.
clips[].playback.url · anyOf 1See schemaExpand this value in the interactive reference.
clips[].playback.url · anyOf 2Alternativeclips[].playback.url · anyOf 2See schemaExpand this value in the interactive reference.
clips[].promptRequiredMay be null. Must match at least one alternative.
clips[].prompt · anyOf 1AlternativeGeneration prompt for owned clips only. Shared and external clips always return null.
clips[].prompt · anyOf 2Alternativeclips[].providerModelNameRequiredMay be null. Must match at least one alternative.
clips[].providerModelName · anyOf 1AlternativeExact Suno model_name value reported for this clip, for example chirp-hawk.
clips[].providerModelName · anyOf 2Alternativeclips[].roleRequiredclips[].titleRequiredMay be null. Must match at least one alternative.
clips[].title · anyOf 1Alternativeclips[].title · anyOf 2Alternativeclips[].updatedAtRequiredMay be null. Must match at least one alternative.
clips[].updatedAt · anyOf 1AlternativeFormat: date-time.
clips[].updatedAt · anyOf 2Alternativeclips[].videoUrlRequiredMay be null. Must match at least one alternative.
clips[].videoUrl · anyOf 1Alternativeclips[].videoUrl · anyOf 2AlternativecreatedAtRequiredFormat: date-time.
deliveryStatusRequiredMay be null. Must match at least one alternative.
deliveryStatus · anyOf 1AlternativeMust match at least one alternative.
deliveryStatus · anyOf 1 · anyOf 1AlternativedeliveryStatus · anyOf 1 · anyOf 2AlternativedeliveryStatus · anyOf 1 · anyOf 3AlternativedeliveryStatus · anyOf 1 · anyOf 4AlternativedeliveryStatus · anyOf 1 · anyOf 5AlternativedeliveryStatus · anyOf 2AlternativefailureReasonRequiredMay be null. Must match at least one alternative.
failureReason · anyOf 1AlternativefailureReason · anyOf 2AlternativefinalClipIdRequiredMay be null. Must match at least one alternative.
finalClipId · anyOf 1AlternativefinalClipId · anyOf 2AlternativefinalUrlRequiredMay be null. Must match at least one alternative.
finalUrl · anyOf 1AlternativefinalUrl · anyOf 2AlternativegenerationIdRequiredCanonical OmnAPI Suno product ID. It equals the originating taskId.
partialFailureRequiredTrue when the generation completed with at least one successful clip and at least one failed clip.
phaseRequiredprogressRequiredMinimum: 0. Maximum: 100.
refundableRequiredretryableRequiredstatusRequiredDefault: "PENDING".
taskIdRequiredupdatedAtRequiredFormat: date-time.
versionRequiredMinimum: 0.
warningCodesRequiredwarningCodes[]Each itemapplication/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
Forbidden: the API key lacks the required scope or its IP policy rejects this request.
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses
Request allowance or task admission capacity exceeded. Follow Retry-After when present; otherwise wait for active tasks and use bounded backoff. Limits do not guarantee throughput. For SSE, this is the HTTP connection response, not an event.
application/json
errorRequirederror.codeRequiredRATE_LIMITED for request and task admission rejections.
error.messageRequirederror.detailsOptionalOptional and scope-dependent. Request limits supply scope/policy/type/limit/current/retryAfterSec. Task admission supplies inFlight/limit/tier, plus scope=apiKey for a key cap. IP rejection can omit details. In-flight rejection does not promise Retry-After.
error.details.currentOptionalMinimum: 0.
error.details.inFlightOptionalMinimum: 0.
error.details.limitOptionalMinimum: 0.
error.details.policyOptionalerror.details.retryAfterSecOptionalMinimum: 1.
error.details.scopeOptionalerror.details.tierOptionalerror.details.typeOptionalsuccessRequiredDefault: false.
application/json
errorRequirederror.codeRequiredApplication-specific error code (see error catalog)
error.messageRequiredHuman readable error message
error.detailsOptionalAdditional error details (optional)
successRequiredAlways false for error responses