Query multiple clips

GET/api/v1/suno/clipsCopy URL

Authentication · x-api-key

Free direct batch read with the same per-clip access projection as the detail endpoint. Preserves request order, reports definitively absent IDs in missingClipIds, and reserves errors for transient per-ID read failures. No Task is created and no credits are charged.

All endpointsRequestResponsesCode

Request

clipIdsquery · Required

string

Responses

200 OK

application/json

Unknown fields are not accepted.

• Response 200 · errorsRequired

  array<object>
  1 field

  • Response 200 · errors[]Each item

    object

    Unknown fields are not accepted.

    4 fields

    • Response 200 · errors[].clipIdRequired

      string

    • Response 200 · errors[].codeRequired

      string

    • Response 200 · errors[].messageRequired

      string

    • Response 200 · errors[].retryableRequired

      boolean

• Response 200 · itemsRequired

  array<object>
  1 field

  • Response 200 · items[]Each item

    object

    Unknown fields are not accepted.

    23 fields

    • Response 200 · items[].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 · items[].audioUrlRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].audioUrl · anyOf 1Alternative

        string

      • Response 200 · items[].audioUrl · anyOf 2Alternative

        null

    • Response 200 · items[].clipIdRequired

      string

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

    • Response 200 · items[].createdAtRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].createdAt · anyOf 1Alternative

        string

        Format: date-time.

      • Response 200 · items[].createdAt · anyOf 2Alternative

        null

    • Response 200 · items[].deliveryStatusRequired

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

    • Response 200 · items[].durationRequired

      number | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].duration · anyOf 1Alternative

        number

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

        Minimum: 0.

      • Response 200 · items[].duration · anyOf 2Alternative

        null

    • Response 200 · items[].errorCodeRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].errorCode · anyOf 1Alternative

        string

      • Response 200 · items[].errorCode · anyOf 2Alternative

        null

    • Response 200 · items[].errorMessageRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].errorMessage · anyOf 1Alternative

        string

      • Response 200 · items[].errorMessage · anyOf 2Alternative

        null

    • Response 200 · items[].imageUrlRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].imageUrl · anyOf 1Alternative

        string

      • Response 200 · items[].imageUrl · anyOf 2Alternative

        null

    • Response 200 · items[].indexRequired

      number

      Minimum: 0.

    • Response 200 · items[].instrumentalRequired

      boolean | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].instrumental · anyOf 1Alternative

        boolean

      • Response 200 · items[].instrumental · anyOf 2Alternative

        null

    • Response 200 · items[].majorModelVersionRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].majorModelVersion · anyOf 1Alternative

        string

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

      • Response 200 · items[].majorModelVersion · anyOf 2Alternative

        null

    • Response 200 · items[].modelRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].model · anyOf 1Alternative

        string

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

      • Response 200 · items[].model · anyOf 2Alternative

        null

    • Response 200 · items[].modelCodeRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].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 · items[].modelCode · anyOf 2Alternative

        null

    • Response 200 · items[].playableRequired

      boolean

    • Response 200 · items[].playbackRequired

      object

      Unknown fields are not accepted.

      8 fields

      • Response 200 · items[].playback.deliveryRequired

        "none" | "chunked" | "progressive"

      • Response 200 · items[].playback.expiresAtRequired

        string | null

        May be null. Must match at least one alternative.

        2 fields / alternatives

        • Response 200 · items[].playback.expiresAt · anyOf 1Alternative

          string

          Format: date-time.

          1 field

          • Response 200 · items[].playback.expiresAt · anyOf 1See schema

            string

            Expand this value in the interactive reference.

            Format: date-time.

        • Response 200 · items[].playback.expiresAt · anyOf 2Alternative

          null
          1 field

          • Response 200 · items[].playback.expiresAt · anyOf 2See schema

            null

            Expand this value in the interactive reference.

      • Response 200 · items[].playback.mimeTypeRequired

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

        May be null. Must match at least one alternative.

        2 fields / alternatives

        • Response 200 · items[].playback.mimeType · anyOf 1Alternative

          "audio/mpeg" | "audio/mp4"

          Must match at least one alternative.

          1 field

          • Response 200 · items[].playback.mimeType · anyOf 1See schema

            "audio/mpeg" | "audio/mp4"

            Expand this value in the interactive reference.

            Must match at least one alternative.

        • Response 200 · items[].playback.mimeType · anyOf 2Alternative

          null
          1 field

          • Response 200 · items[].playback.mimeType · anyOf 2See schema

            null

            Expand this value in the interactive reference.

      • Response 200 · items[].playback.retryAfterMsRequired

        number | null

        May be null. Must match at least one alternative.

        2 fields / alternatives

        • Response 200 · items[].playback.retryAfterMs · anyOf 1Alternative

          number

          Minimum: 0.

          1 field

          • Response 200 · items[].playback.retryAfterMs · anyOf 1See schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

        • Response 200 · items[].playback.retryAfterMs · anyOf 2Alternative

          null
          1 field

          • Response 200 · items[].playback.retryAfterMs · anyOf 2See schema

            null

            Expand this value in the interactive reference.

      • Response 200 · items[].playback.seekableRequired

        boolean

      • Response 200 · items[].playback.sessionCreateUrlRequired

        string | null

        May be null. Must match at least one alternative.

        2 fields / alternatives

        • Response 200 · items[].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.

          1 field

          • Response 200 · items[].playback.sessionCreateUrl · anyOf 1See schema

            string

            Expand this value in the interactive reference.

            Deprecated; omit in new integrations.

        • Response 200 · items[].playback.sessionCreateUrl · anyOf 2Alternative

          null
          1 field

          • Response 200 · items[].playback.sessionCreateUrl · anyOf 2See schema

            null

            Expand this value in the interactive reference.

      • Response 200 · items[].playback.stateRequired

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

      • Response 200 · items[].playback.urlRequired

        string | null

        May be null. Must match at least one alternative.

        2 fields / alternatives

        • Response 200 · items[].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.

          1 field

          • Response 200 · items[].playback.url · anyOf 1See schema

            string

            Expand this value in the interactive reference.

        • Response 200 · items[].playback.url · anyOf 2Alternative

          null
          1 field

          • Response 200 · items[].playback.url · anyOf 2See schema

            null

            Expand this value in the interactive reference.

    • Response 200 · items[].promptRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].prompt · anyOf 1Alternative

        string

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

      • Response 200 · items[].prompt · anyOf 2Alternative

        null

    • Response 200 · items[].providerModelNameRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].providerModelName · anyOf 1Alternative

        string

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

      • Response 200 · items[].providerModelName · anyOf 2Alternative

        null

    • Response 200 · items[].roleRequired

      "candidate" | "final"

    • Response 200 · items[].tagsRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].tags · anyOf 1Alternative

        string

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

      • Response 200 · items[].tags · anyOf 2Alternative

        null

    • Response 200 · items[].titleRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].title · anyOf 1Alternative

        string

      • Response 200 · items[].title · anyOf 2Alternative

        null

    • Response 200 · items[].updatedAtRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].updatedAt · anyOf 1Alternative

        string

        Format: date-time.

      • Response 200 · items[].updatedAt · anyOf 2Alternative

        null

    • Response 200 · items[].videoUrlRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].videoUrl · anyOf 1Alternative

        string

      • Response 200 · items[].videoUrl · anyOf 2Alternative

        null

• Response 200 · missingClipIdsRequired

  array<string>
  1 field

  • Response 200 · missingClipIds[]Each item

    string

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

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?clipIds={clipIds}' \
  --header "x-api-key: $OMNAPI_KEY"

Node.js

const response = await fetch("https://api.omnapi.com/api/v1/suno/clips?clipIds={clipIds}", {
  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?clipIds={clipIds}",
    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