Suno Clip Reads and Timed Lyrics

Product overview · Task model

Read clips and music metadata

Use these APIs after a Generation returns concrete clipIds, or when migrating stored legacy mid values. They never accept a Task ID in place of a clip ID.

Read clip detail and batches

API	When to use it	Billing
GET /api/v1/suno/clips/{clipId}	Read one known external clip ID	Free direct read; no Task
GET /api/v1/suno/clips?clipIds=a,b,c	Resolve several external clip IDs in caller order	Free direct read; no Task

Clip detail

curl https://api.omnapi.com/api/v1/suno/clips/clip_123 \
  -H "x-api-key: $OMNAPI_KEY"

Batch clips

curl "https://api.omnapi.com/api/v1/suno/clips?clipIds=clip_a,clip_b" \
  -H "x-api-key: $OMNAPI_KEY"

clipIds contains external Suno IDs (legacy mid values), not Task IDs or internal row IDs. clipIds is the only accepted batch parameter.

Direct detail returns one normalized clip:

{
  "clipId": "clip_a",
  "accessLevel": "owned",
  "index": 0,
  "role": "candidate",
  "deliveryStatus": "complete",
  "title": "Late Train",
  "tags": "city pop, warm bass",
  "prompt": "bright city pop about a late train home",
  "model": "chirp-hawk",
  "modelCode": "chirp-hawk",
  "providerModelName": "chirp-goose",
  "majorModelVersion": "v6",
  "instrumental": false,
  "audioUrl": "https://media.example.com/song.m4a",
  "imageUrl": "https://...",
  "videoUrl": null,
  "playable": true,
  "playback": {
    "state": "final",
    "url": "https://media.example.com/song.m4a",
    "mimeType": "audio/mp4",
    "delivery": "progressive",
    "seekable": true,
    "expiresAt": null,
    "retryAfterMs": null,
    "sessionCreateUrl": null
  },
  "duration": 183.2,
  "errorCode": null,
  "errorMessage": null,
  "createdAt": "2026-07-30T12:00:00.000Z",
  "updatedAt": "2026-07-30T12:01:00.000Z"
}

Model identity is intentionally split into independent fields:

Field	Meaning
modelCode	Canonical OmnAPI model selected for an owned generation; null for a direct clip with no local task
providerModelName	Exact model name reported for the clip
majorModelVersion	Exact major model version reported for the clip
model	Compatibility label; new integrations should use the explicit fields above

Merely readable external clips redact all model fields. Shared clips may return the two provider-reported fields but do not invent a local modelCode. Owned clips return tags and prompt; shared public or remixable clips return their public style tags while keeping prompt: null; external clips keep both fields null. If tags or duration become available after the first completion snapshot, later Clip and Generation reads automatically return the repaired metadata.

Batch responses never hide partial results:

{
  "items": [
    {
      "clipId": "clip_a",
      "index": 0,
      "role": "candidate",
      "deliveryStatus": "complete",
      "audioUrl": "https://media.example.com/song.m4a",
      "playable": true
    }
  ],
  "missingClipIds": [
    "clip_b"
  ],
  "errors": []
}

The batch response preserves requested order. missingClipIds is the only place for clips that were definitively not found or not visible. errors[] is reserved for transient per-ID read failures and contains code, message, and retryable. A missing or failed sibling never removes a successful item. Public clip results omit account identity and provider-only controls.

Read aligned lyrics

Call GET /api/v1/suno/clips/{clipId}/timeline when playback, karaoke, or subtitle rendering needs word and line timing. This operation costs 1 standard credit and returns:

• words[] with word, start, end, and optional confidence;
• lines[] with line timing, optional section, and nested words[];
• waveform_data for time-aligned visualization.

curl https://api.omnapi.com/api/v1/suno/clips/clip_123/timeline \
  -H "x-api-key: $OMNAPI_KEY"

Read audio analysis

Call GET /api/v1/suno/clips/{clipId}/audio-analysis when an editor or visualizer needs musical structure. The free result exposes typed outputResults: { clipId, downbeats, key, waveform }.

curl https://api.omnapi.com/api/v1/suno/clips/clip_123/audio-analysis \
  -H "x-api-key: $OMNAPI_KEY"

Recommend styles

Call GET /api/v1/suno/styles/recommend to obtain prompt-ready style names. Pass an optional comma-separated exclude list to remove up to 50 unwanted styles. The free result is outputResults: { recommendStyles }.

curl "https://api.omnapi.com/api/v1/suno/styles/recommend?exclude=metal,opera" \
  -H "x-api-key: $OMNAPI_KEY"

Handle bounded read tasks

Timeline, analysis, and style recommendation use this read-style Task response:

Expand the complete JSON example

{
  "taskId": "task_read_01J...",
  "status": "COMPLETED",
  "creditsRequired": 1,
  "creditsCharged": 1,
  "outputResults": {
    "clipId": "clip_a",
    "words": [
      {
        "word": "Neon",
        "start": 1.2,
        "end": 1.6,
        "confidence": 0.98
      }
    ],
    "lines": [
      {
        "text": "Neon rain",
        "start": 1.2,
        "end": 2.1,
        "words": [
          {
            "word": "Neon",
            "start": 1.2,
            "end": 1.6
          },
          {
            "word": "rain",
            "start": 1.7,
            "end": 2.1
          }
        ]
      }
    ],
    "waveform_data": []
  },
  "resources": [],
  "pollUrl": null,
  "errorCode": null,
  "errorMessage": null,
  "processingDuration": 1820,
  "processingDurationText": "1.8s"
}

The example is a timeline response. Audio analysis replaces outputResults with { clipId, downbeats, key, waveform }; style recommendation returns { recommendStyles }. If the bounded inline lookup is not ready, HTTP 202 returns the same envelope with status: "PROCESSING" and a non-null pollUrl. Polling that Task, receiving its terminal SSE event, or processing its webhook preserves the same feature-specific outputResults shape as the direct 200 response.

Check availability and resource access

Read delivery health

Call GET /api/v1/suno/availability before enabling paid Suno actions in a customer UI, and again after a transient availability failure.

GET /api/v1/suno/availability returns available, degraded, unavailable, or unknown, plus advisory checks and retryAfterSec. It also reports whether advanced operations are currently available. The checks use customer-safe service, processing, capacity, advanced-operation, and delivery categories. The endpoint is advisory; the task receipt and terminal task state remain authoritative.

curl https://api.omnapi.com/api/v1/suno/availability \
  -H "x-api-key: $OMNAPI_KEY"

{
  "status": "available",
  "checkedAt": "2026-07-30T12:00:00.000Z",
  "retryAfterSec": null,
  "message": "Suno delivery is available",
  "guidance": "Requests can be submitted normally.",
  "subscriptionOperationsAvailable": true,
  "checks": [
    {
      "name": "generation-capacity",
      "status": "pass",
      "message": "Generation capacity is available"
    }
  ]
}

subscriptionOperationsAvailable describes the health of supported subscription-backed operations. It does not make internal Remaster, Infill, Editor, Video, Opus, or standalone Concat endpoints public.

Respect resource access

Some clips and Voices carry access relationships that must be preserved for follow-up operations. When a referenced resource is not compatible with the requested action, the task fails with SUNO_RESOURCE_ACCESS_DENIED. Do not blind-retry with the same resource; select another compatible resource or upload audio that you have the right to use.

Public Voices are the exception at the product boundary: a caller who knows the public Voice ID may read it and use it for generation even when another OmnAPI user created it. Availability and access are revalidated when generation starts.