Get clip detail

GET/api/v1/suno/clips/{clipId}Copy URL

Authentication · x-api-key

Free direct resource read. `clipId` is the external Suno ID (legacy `mid`), never a TaskResult database ID. `accessLevel` controls field projection only: owned clips return the full contract, shared clips are public or remixable, and other readable external clips return minimal media fields. It does not grant derive or export permission. No Task is created or charged.

All endpointsRequestResponsesCode

Request

clipIdpath · Required

string

Suno clip identifier returned by a Generation or clip read.

Responses

200 OK

application/json

Unknown fields are not accepted.

• Response 200 · accessLevelRequired

  "owned" | "shared" | "external"

  Read 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.

• Response 200 · audioUrlRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · audioUrl · anyOf 1Alternative

    string

  • Response 200 · audioUrl · anyOf 2Alternative

    null

• Response 200 · clipIdRequired

  string

  Suno clip identifier (`mid`); do not substitute an OmnAPI resource identifier.

• Response 200 · createdAtRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · createdAt · anyOf 1Alternative

    string

    Format: date-time.

  • Response 200 · createdAt · anyOf 2Alternative

    null

• Response 200 · deliveryStatusRequired

  "submitted" | "queued" | "streaming" | "complete" | "error"

• Response 200 · durationRequired

  number | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · duration · anyOf 1Alternative

    number

    Clip duration in seconds. Missing eventually-consistent metadata is repaired on later reads.

    Minimum: 0.

  • Response 200 · duration · anyOf 2Alternative

    null

• Response 200 · errorCodeRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · errorCode · anyOf 1Alternative

    string

  • Response 200 · errorCode · anyOf 2Alternative

    null

• Response 200 · errorMessageRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · errorMessage · anyOf 1Alternative

    string

  • Response 200 · errorMessage · anyOf 2Alternative

    null

• Response 200 · imageUrlRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · imageUrl · anyOf 1Alternative

    string

  • Response 200 · imageUrl · anyOf 2Alternative

    null

• Response 200 · indexRequired

  number

  Minimum: 0.

• Response 200 · instrumentalRequired

  boolean | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · instrumental · anyOf 1Alternative

    boolean

  • Response 200 · instrumental · anyOf 2Alternative

    null

• Response 200 · majorModelVersionRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · majorModelVersion · anyOf 1Alternative

    string

    Exact Suno major_model_version value reported for this clip, for example v4.5-all.

  • Response 200 · majorModelVersion · anyOf 2Alternative

    null

• Response 200 · modelRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · model · anyOf 1Alternative

    string

    Compatibility model label. Prefer modelCode, providerModelName and majorModelVersion for unambiguous integrations.

  • Response 200 · model · anyOf 2Alternative

    null

• Response 200 · modelCodeRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · modelCode · anyOf 1Alternative

    string

    Canonical OmnAPI model code selected for an owned generation. Null when a clip is read directly from Suno without a local task.

  • Response 200 · modelCode · anyOf 2Alternative

    null

• Response 200 · playableRequired

  boolean

• Response 200 · playbackRequired

  object

  Unknown fields are not accepted.

  8 fields

  • Response 200 · playback.deliveryRequired

    "none" | "chunked" | "progressive"

  • Response 200 · playback.expiresAtRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · playback.expiresAt · anyOf 1Alternative

      string

      Format: date-time.

    • Response 200 · playback.expiresAt · anyOf 2Alternative

      null

  • Response 200 · playback.mimeTypeRequired

    "audio/mpeg" | "audio/mp4" | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · playback.mimeType · anyOf 1Alternative

      "audio/mpeg" | "audio/mp4"

      Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · playback.mimeType · anyOf 1 · anyOf 1Alternative

        "audio/mpeg"

      • Response 200 · playback.mimeType · anyOf 1 · anyOf 2Alternative

        "audio/mp4"

    • Response 200 · playback.mimeType · anyOf 2Alternative

      null

  • Response 200 · playback.retryAfterMsRequired

    number | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · playback.retryAfterMs · anyOf 1Alternative

      number

      Minimum: 0.

    • Response 200 · playback.retryAfterMs · anyOf 2Alternative

      null

  • Response 200 · playback.seekableRequired

    boolean

  • Response 200 · playback.sessionCreateUrlRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · playback.sessionCreateUrl · anyOf 1Alternative

      string

      Deprecated compatibility field. New integrations should use playback.url directly; no separate playback-session request is needed.

      Deprecated; omit in new integrations.

    • Response 200 · playback.sessionCreateUrl · anyOf 2Alternative

      null

  • Response 200 · playback.stateRequired

    "preparing" | "live" | "final" | "error" | "unavailable"

  • Response 200 · playback.urlRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · playback.url · anyOf 1Alternative

      string

      Current 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.

    • Response 200 · playback.url · anyOf 2Alternative

      null

• Response 200 · promptRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · prompt · anyOf 1Alternative

    string

    Generation prompt for owned clips only. Shared and external clips always return null.

  • Response 200 · prompt · anyOf 2Alternative

    null

• Response 200 · providerModelNameRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · providerModelName · anyOf 1Alternative

    string

    Exact Suno model_name value reported for this clip, for example chirp-hawk.

  • Response 200 · providerModelName · anyOf 2Alternative

    null

• Response 200 · roleRequired

  "candidate" | "final"

• Response 200 · tagsRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · tags · anyOf 1Alternative

    string

    Public style tags for owned and shared clips. Null for external clips or before metadata propagation completes.

  • Response 200 · tags · anyOf 2Alternative

    null

• Response 200 · titleRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · title · anyOf 1Alternative

    string

  • Response 200 · title · anyOf 2Alternative

    null

• Response 200 · updatedAtRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · updatedAt · anyOf 1Alternative

    string

    Format: date-time.

  • Response 200 · updatedAt · anyOf 2Alternative

    null

• Response 200 · videoUrlRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · videoUrl · anyOf 1Alternative

    string

  • Response 200 · videoUrl · anyOf 2Alternative

    null

400 Bad Request

application/json

• Response 400 · errorRequired

  object
  3 fields

  • Response 400 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 400 · error.messageRequired

    string

    Human readable error message

  • Response 400 · error.detailsOptional

    object

    Additional error details (optional)

• Response 400 · successRequired

  false

  Always false for error responses

401 Unauthorized

application/json

• Response 401 · errorRequired

  object
  3 fields

  • Response 401 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 401 · error.messageRequired

    string

    Human readable error message

  • Response 401 · error.detailsOptional

    object

    Additional error details (optional)

• Response 401 · successRequired

  false

  Always false for error responses

403 Forbidden

Forbidden: the API key lacks the required scope or its IP policy rejects this request.

application/json

• Response 403 · errorRequired

  object
  3 fields

  • Response 403 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 403 · error.messageRequired

    string

    Human readable error message

  • Response 403 · error.detailsOptional

    object

    Additional error details (optional)

• Response 403 · successRequired

  false

  Always false for error responses

404 Not Found

application/json

• Response 404 · errorRequired

  object
  3 fields

  • Response 404 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 404 · error.messageRequired

    string

    Human readable error message

  • Response 404 · error.detailsOptional

    object

    Additional error details (optional)

• Response 404 · successRequired

  false

  Always 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 · errorRequired

  object
  3 fields

  • Response 429 · error.codeRequired

    string

    RATE_LIMITED for request and task admission rejections.

  • Response 429 · error.messageRequired

    string

  • Response 429 · error.detailsOptional

    object

    Optional 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.currentOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.inFlightOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.limitOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.policyOptional

      "operation" | "query"

    • Response 429 · error.details.retryAfterSecOptional

      integer

      Minimum: 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 · successRequired

  false

  Default: false.

500 Internal Server Error

application/json

• Response 500 · errorRequired

  object
  3 fields

  • Response 500 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 500 · error.messageRequired

    string

    Human readable error message

  • Response 500 · error.detailsOptional

    object

    Additional error details (optional)

• Response 500 · successRequired

  false

  Always false for error responses

503 Service Unavailable

application/json

• Response 503 · errorRequired

  object
  3 fields

  • Response 503 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 503 · error.messageRequired

    string

    Human readable error message

  • Response 503 · error.detailsOptional

    object

    Additional error details (optional)

• Response 503 · successRequired

  false

  Always false for error responses

Request example

Wrap lines

cURL

curl --globoff --request GET \
  --url 'https://api.omnapi.com/api/v1/suno/clips/{clipId}' \
  --header "x-api-key: $OMNAPI_KEY"

Node.js

const response = await fetch("https://api.omnapi.com/api/v1/suno/clips/{clipId}", {
  method: "GET",
  headers: {
    "x-api-key": process.env.OMNAPI_KEY,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.text());

Python

import os
import requests

response = requests.request(
    "GET", "https://api.omnapi.com/api/v1/suno/clips/{clipId}",
    headers={
        "x-api-key": os.environ["OMNAPI_KEY"],
    },
    timeout=60,
)
response.raise_for_status()
print(response.text)

Set URL and header variables.

Interactive API Explorer → · OpenAPI JSON