excludequery · OptionalRecommend Styles
/api/v1/suno/styles/recommendAuthentication · x-api-key
Style suggestions. Short sync-wait; returns 202 with taskId on timeout.
Request
Responses
200 OK
application/json
Unknown fields are not accepted.
-
Response 200 ·
creditsChargedRequirednumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
creditsCharged · anyOf 1AlternativenumberExact credits actually charged
Minimum: 0.
-
Response 200 ·
creditsCharged · anyOf 2Alternativenull
-
-
Response 200 ·
creditsRequiredRequirednumberExact credits deducted to start the task
Minimum: 0.
-
Response 200 ·
errorCodeRequiredstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
errorCode · anyOf 1AlternativestringError code if task failed
-
Response 200 ·
errorCode · anyOf 2Alternativenull
-
-
Response 200 ·
errorMessageRequiredstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
errorMessage · anyOf 1AlternativestringError message if task failed
-
Response 200 ·
errorMessage · anyOf 2Alternativenull
-
-
Response 200 ·
outputResultsRequiredobject | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
outputResults · anyOf 1AlternativeobjectUnknown fields are not accepted.
1 field
-
Response 200 ·
outputResults · anyOf 1.recommendStylesRequiredarray<string>1 field
-
Response 200 ·
outputResults · anyOf 1.recommendStyles[]Each itemstring
-
-
-
Response 200 ·
outputResults · anyOf 2Alternativenull
-
-
Response 200 ·
processingDurationRequirednumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
processingDuration · anyOf 1AlternativenumberProcessing duration in milliseconds
-
Response 200 ·
processingDuration · anyOf 2Alternativenull
-
-
Response 200 ·
processingDurationTextRequiredstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
processingDurationText · anyOf 1AlternativestringHuman-readable processing duration, e.g. 16.2s
-
Response 200 ·
processingDurationText · anyOf 2Alternativenull
-
-
Response 200 ·
statusRequired"PENDING" | "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELLED"Default: "PENDING".
-
Response 200 ·
taskIdRequiredstringTask unique identifier
-
Response 200 ·
pollUrlOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
pollUrl · anyOf 1AlternativestringSet only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.
-
Response 200 ·
pollUrl · anyOf 2Alternativenull
-
-
Response 200 ·
resourcesOptionalarray<object>Standardized resources produced by the task
1 field
-
Response 200 ·
resources[]Each itemobjectA consumable resource produced by the task.
19 fields
-
Response 200 ·
resources[].idRequiredstringStable resource id (OmnAPI resource id).
-
Response 200 ·
resources[].indexRequirednumberStable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.
Minimum: 0.
-
Response 200 ·
resources[].roleRequired"candidate" | "final" | "stem" | "fallback" | "output"How clients should interpret the resource. Prefer `final` when present; `candidate` items remain selectable alternatives.
-
Response 200 ·
resources[].typeRequired"MUSIC" | "IMAGE" | "VIDEO" | "AUDIO" | "TEXT" | "METADATA"Uppercase resource kind. MUSIC carries a song URL and optional thumbnailUrl; TEXT carries inline content. Optional fields depend on the operation.
-
Response 200 ·
resources[].assetIdOptionalstringStable OmnAPI-owned asset id when available.
-
Response 200 ·
resources[].assetStatusOptional"READY" | "EXPIRED" | "DELETING" | "DELETED" -
Response 200 ·
resources[].byteLengthOptionalnumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].byteLength · anyOf 1AlternativenumberResource size in bytes.
-
Response 200 ·
resources[].byteLength · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].contentOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].content · anyOf 1AlternativestringInline text content (e.g. lyrics).
-
Response 200 ·
resources[].content · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].contentTypeOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].contentType · anyOf 1AlternativestringResource content type.
-
Response 200 ·
resources[].contentType · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].durationOptionalnumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].duration · anyOf 1Alternativenumber -
Response 200 ·
resources[].duration · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].durationSecOptionalnumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].durationSec · anyOf 1AlternativenumberResource duration in seconds.
-
Response 200 ·
resources[].durationSec · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].heightOptionalnumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].height · anyOf 1Alternativenumber -
Response 200 ·
resources[].height · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].metadataOptionalobject | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].metadata · anyOf 1Alternativeobject -
Response 200 ·
resources[].metadata · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].retainedUntilOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].retainedUntil · anyOf 1AlternativestringFormat: date-time.
-
Response 200 ·
resources[].retainedUntil · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].thumbnailUrlOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].thumbnailUrl · anyOf 1Alternativestring -
Response 200 ·
resources[].thumbnailUrl · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].titleOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].title · anyOf 1Alternativestring -
Response 200 ·
resources[].title · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].urlOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].url · anyOf 1AlternativestringPresigned/public URL.
-
Response 200 ·
resources[].url · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].urlExpiresAtOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].urlExpiresAt · anyOf 1AlternativestringFormat: date-time.
-
Response 200 ·
resources[].urlExpiresAt · anyOf 2Alternativenull
-
-
Response 200 ·
resources[].widthOptionalnumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 200 ·
resources[].width · anyOf 1Alternativenumber -
Response 200 ·
resources[].width · anyOf 2Alternativenull
-
-
-
202 Accepted
application/json
Unknown fields are not accepted.
-
Response 202 ·
creditsChargedRequirednumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
creditsCharged · anyOf 1AlternativenumberExact credits actually charged
Minimum: 0.
-
Response 202 ·
creditsCharged · anyOf 2Alternativenull
-
-
Response 202 ·
creditsRequiredRequirednumberExact credits deducted to start the task
Minimum: 0.
-
Response 202 ·
errorCodeRequiredstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
errorCode · anyOf 1AlternativestringError code if task failed
-
Response 202 ·
errorCode · anyOf 2Alternativenull
-
-
Response 202 ·
errorMessageRequiredstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
errorMessage · anyOf 1AlternativestringError message if task failed
-
Response 202 ·
errorMessage · anyOf 2Alternativenull
-
-
Response 202 ·
outputResultsRequiredobject | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
outputResults · anyOf 1AlternativeobjectUnknown fields are not accepted.
1 field
-
Response 202 ·
outputResults · anyOf 1.recommendStylesRequiredarray<string>1 field
-
Response 202 ·
outputResults · anyOf 1.recommendStyles[]Each itemstring
-
-
-
Response 202 ·
outputResults · anyOf 2Alternativenull
-
-
Response 202 ·
processingDurationRequirednumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
processingDuration · anyOf 1AlternativenumberProcessing duration in milliseconds
-
Response 202 ·
processingDuration · anyOf 2Alternativenull
-
-
Response 202 ·
processingDurationTextRequiredstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
processingDurationText · anyOf 1AlternativestringHuman-readable processing duration, e.g. 16.2s
-
Response 202 ·
processingDurationText · anyOf 2Alternativenull
-
-
Response 202 ·
statusRequired"PENDING" | "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELLED"Default: "PENDING".
-
Response 202 ·
taskIdRequiredstringTask unique identifier
-
Response 202 ·
pollUrlOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
pollUrl · anyOf 1AlternativestringSet only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.
-
Response 202 ·
pollUrl · anyOf 2Alternativenull
-
-
Response 202 ·
resourcesOptionalarray<object>Standardized resources produced by the task
1 field
-
Response 202 ·
resources[]Each itemobjectA consumable resource produced by the task.
19 fields
-
Response 202 ·
resources[].idRequiredstringStable resource id (OmnAPI resource id).
-
Response 202 ·
resources[].indexRequirednumberStable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.
Minimum: 0.
-
Response 202 ·
resources[].roleRequired"candidate" | "final" | "stem" | "fallback" | "output"How clients should interpret the resource. Prefer `final` when present; `candidate` items remain selectable alternatives.
-
Response 202 ·
resources[].typeRequired"MUSIC" | "IMAGE" | "VIDEO" | "AUDIO" | "TEXT" | "METADATA"Uppercase resource kind. MUSIC carries a song URL and optional thumbnailUrl; TEXT carries inline content. Optional fields depend on the operation.
-
Response 202 ·
resources[].assetIdOptionalstringStable OmnAPI-owned asset id when available.
-
Response 202 ·
resources[].assetStatusOptional"READY" | "EXPIRED" | "DELETING" | "DELETED" -
Response 202 ·
resources[].byteLengthOptionalnumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].byteLength · anyOf 1AlternativenumberResource size in bytes.
-
Response 202 ·
resources[].byteLength · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].contentOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].content · anyOf 1AlternativestringInline text content (e.g. lyrics).
-
Response 202 ·
resources[].content · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].contentTypeOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].contentType · anyOf 1AlternativestringResource content type.
-
Response 202 ·
resources[].contentType · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].durationOptionalnumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].duration · anyOf 1Alternativenumber -
Response 202 ·
resources[].duration · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].durationSecOptionalnumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].durationSec · anyOf 1AlternativenumberResource duration in seconds.
-
Response 202 ·
resources[].durationSec · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].heightOptionalnumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].height · anyOf 1Alternativenumber -
Response 202 ·
resources[].height · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].metadataOptionalobject | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].metadata · anyOf 1Alternativeobject -
Response 202 ·
resources[].metadata · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].retainedUntilOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].retainedUntil · anyOf 1AlternativestringFormat: date-time.
-
Response 202 ·
resources[].retainedUntil · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].thumbnailUrlOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].thumbnailUrl · anyOf 1Alternativestring -
Response 202 ·
resources[].thumbnailUrl · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].titleOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].title · anyOf 1Alternativestring -
Response 202 ·
resources[].title · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].urlOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].url · anyOf 1AlternativestringPresigned/public URL.
-
Response 202 ·
resources[].url · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].urlExpiresAtOptionalstring | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].urlExpiresAt · anyOf 1AlternativestringFormat: date-time.
-
Response 202 ·
resources[].urlExpiresAt · anyOf 2Alternativenull
-
-
Response 202 ·
resources[].widthOptionalnumber | nullMay be null. Must match at least one alternative.
2 fields / alternatives
-
Response 202 ·
resources[].width · anyOf 1Alternativenumber -
Response 202 ·
resources[].width · anyOf 2Alternativenull
-
-
-
400 Bad Request
application/json
-
Response 400 ·
errorRequiredobject3 fields
-
Response 400 ·
error.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 400 ·
error.messageRequiredstringHuman readable error message
-
Response 400 ·
error.detailsOptionalobjectAdditional error details (optional)
-
-
Response 400 ·
successRequiredfalseAlways false for error responses
401 Unauthorized
application/json
-
Response 401 ·
errorRequiredobject3 fields
-
Response 401 ·
error.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 401 ·
error.messageRequiredstringHuman readable error message
-
Response 401 ·
error.detailsOptionalobjectAdditional error details (optional)
-
-
Response 401 ·
successRequiredfalseAlways false for error responses
402 Payment Required
application/json
-
Response 402 ·
errorRequiredobject3 fields
-
Response 402 ·
error.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 402 ·
error.messageRequiredstringHuman readable error message
-
Response 402 ·
error.detailsOptionalobjectAdditional error details (optional)
-
-
Response 402 ·
successRequiredfalseAlways false for error responses
403 Forbidden
Forbidden: the API key lacks the required scope or its IP policy rejects this request. Forbidden: API-key scope/IP restrictions or billing hold. A positive balance does not bypass payment review. Check GET /api/v1/account/credits billingStatus before further paid requests.
application/json
-
Response 403 ·
errorRequiredobject3 fields
-
Response 403 ·
error.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 403 ·
error.messageRequiredstringHuman readable error message
-
Response 403 ·
error.detailsOptionalobjectAdditional error details (optional)
-
-
Response 403 ·
successRequiredfalseAlways false for error responses
422 Unprocessable Entity
application/json
-
Response 422 ·
errorRequiredobject3 fields
-
Response 422 ·
error.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 422 ·
error.messageRequiredstringHuman readable error message
-
Response 422 ·
error.detailsOptionalobjectAdditional error details (optional)
-
-
Response 422 ·
successRequiredfalseAlways false for error responses
429 Too Many Requests
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
-
Response 429 ·
errorRequiredobject3 fields
-
Response 429 ·
error.codeRequiredstringRATE_LIMITED for request and task admission rejections.
-
Response 429 ·
error.messageRequiredstring -
Response 429 ·
error.detailsOptionalobjectOptional 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.
8 fields
-
Response 429 ·
error.details.currentOptionalintegerMinimum: 0.
-
Response 429 ·
error.details.inFlightOptionalintegerMinimum: 0.
-
Response 429 ·
error.details.limitOptionalintegerMinimum: 0.
-
Response 429 ·
error.details.policyOptional"operation" | "query" -
Response 429 ·
error.details.retryAfterSecOptionalintegerMinimum: 1.
-
Response 429 ·
error.details.scopeOptional"user" | "api-key" | "ip" | "apiKey" -
Response 429 ·
error.details.tierOptional"FREE" | "PREMIUM" | "ENTERPRISE" -
Response 429 ·
error.details.typeOptional"rps" | "daily" | "monthly"
-
-
-
Response 429 ·
successRequiredfalseDefault: false.
500 Internal Server Error
application/json
-
Response 500 ·
errorRequiredobject3 fields
-
Response 500 ·
error.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 500 ·
error.messageRequiredstringHuman readable error message
-
Response 500 ·
error.detailsOptionalobjectAdditional error details (optional)
-
-
Response 500 ·
successRequiredfalseAlways false for error responses
503 Service Unavailable
application/json
-
Response 503 ·
errorRequiredobject3 fields
-
Response 503 ·
error.codeRequiredstringApplication-specific error code (see error catalog)
-
Response 503 ·
error.messageRequiredstringHuman readable error message
-
Response 503 ·
error.detailsOptionalobjectAdditional error details (optional)
-
-
Response 503 ·
successRequiredfalseAlways false for error responses