Skip to content

    Subtitles

    Create subtitles from audio

    Supply an audio URL and get timed lyrics as SRT, VTT, LRC, or JSON files. Use them for captions or lyric displays. Quote first to check the price. For captions inside a music video, use automatic MV subtitles.

    Use this flow:

    1. POST /api/v1/subtitles/quote to estimate credits and public price.
    2. POST /api/v1/subtitles with an Idempotency-Key.
    3. Poll GET /api/v1/subtitles/{taskId}.
    4. Read artifacts.srtUrl, artifacts.vttUrl, artifacts.lrcUrl, or artifacts.jsonUrl from the completed task.

    source.durationSec is optional. If omitted, OmnAPI safely probes the public audio URL before quote/create and uses the server-detected duration for pricing, budget checks, and queue sizing. Send it only as a client hint when you already know the duration.


    For a new job, generate and save a key once. Retry with the same route, key, and body.

    Terminal window
    export REQUEST_KEY="$(uuidgen)"
    Terminal window
    curl -X POST https://api.omnapi.com/api/v1/subtitles/quote \
    -H "x-api-key: $OMNAPI_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "source": {
    "type": "audio",
    "audioUrl": "https://example.com/song.mp3"
    },
    "budget": {
    "maxCostUsdPerMin": 0.05
    }
    }'

    Response example (excerpt):

    HTTP 200 · Response excerpt

    {
    "credits": 1,
    "durationSec": 60,
    "estimatedUsd": 0.02,
    "maxCostUsdPerMin": 0.05,
    "publicUsdPerMin": 0.02
    }

    budget.maxCostUsdPerMin is a public price guard. Quote returns both the active price and submitted ceiling so clients can decide before creating a task. Create fails with SUBTITLE_BUDGET_EXCEEDED before credits are deducted when the active subtitle price is above the submitted ceiling.

    Quote accepts the same request envelope as create, including mode, language, outputs, maxCredits, and config, although only source and budget fields affect the current estimate.


    Terminal window
    curl -X POST https://api.omnapi.com/api/v1/subtitles \
    -H "x-api-key: $OMNAPI_KEY" \
    -H "Idempotency-Key: $REQUEST_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "mode": "extract",
    "source": {
    "type": "audio",
    "audioUrl": "https://example.com/song.mp3"
    },
    "language": "auto",
    "outputs": ["srt", "json", "vtt", "lrc"],
    "budget": {
    "maxCostUsdPerMin": 0.05
    },
    "config": {
    "metadata": {
    "purpose": "mv-caption"
    }
    }
    }'

    Response example (excerpt):

    HTTP 200 · Response excerpt

    {
    "taskId": "task_01J...",
    "status": "PENDING",
    "creditsRequired": 1,
    "pollUrl": "/api/v1/subtitles/task_01J..."
    }
    Required, optional and null

    Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

    Only the listed fields are accepted in this object.

    • Request · sourceRequired

      object

      Public source media or product reference.

      Only the listed fields are accepted in this object.

      3 fields
      • Request · source.audioUrlRequired

        string

        Public HTTP(S) audio URL.

        Format: uri.

      • Request · source.typeRequired

        "audio"

        Source or product type discriminator.

      • Request · source.durationSecOptional

        number

        Requested or known media duration in seconds.

        Minimum: 1. Maximum: 600.

    • Request · budgetOptional

      object

      Public price guard for this request.

      Only the listed fields are accepted in this object.

      1 field
      • Request · budget.maxCostUsdPerMinOptional

        number

        Maximum accepted public subtitle price in USD per minute.

        Minimum: 0.001. Maximum: 1.

    • Request · configOptional

      object

      Standard task configuration: priority, tags, metadata, and webhookUrl.

      4 fields
      • Request · config.metadataOptional

        object

        Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.

        1 field
      • Request · config.priorityOptional

        number

        Task priority 1-10 (higher = sooner). Default 5.

        Minimum: 1. Maximum: 10. Default: 5.

      • Request · config.tagsOptional

        array<string>

        Free-form labels for filtering. Up to 20, 100 chars each.

        Maximum items: 20.

        1 field
        • Request · config.tags[]Each item

          string

          Maximum characters: 100.

      • Request · config.webhookUrlOptional

        string

        URL to receive task.* lifecycle events via the central webhook service.

        Format: uri.

    • Request · languageOptional

      string

      Requested or known language code/name.

      Minimum characters: 2. Maximum characters: 16.

    • Request · maxCreditsOptional

      number

      Maximum OmnAPI credits authorized for this paid request.

      Minimum: 1.

    • Request · modeOptional

      "extract"

      Operation or product mode discriminator for this schema variant.

    • Request · outputsOptional

      array<"srt" | "vtt" | "lrc" | "json">

      Requested subtitle artifact formats.

      Minimum items: 1. Maximum items: 4.

      1 field
      • Request · outputs[]Each item

        "srt" | "vtt" | "lrc" | "json"
    Terminal window
    curl https://api.omnapi.com/api/v1/subtitles/task_01J... \
    -H "x-api-key: $OMNAPI_KEY"

    Completed response (excerpt):

    HTTP 200 · Response excerpt

    {
    "taskId": "task_01J...",
    "status": "COMPLETED",
    "progress": 100,
    "lyrics": "First lyric line\nSecond lyric line",
    "timeline": {
    "lines": [
    {
    "text": "First lyric line",
    "startSec": 0.12,
    "endSec": 3.4,
    "section": "Verse 1"
    }
    ],
    "words": []
    },
    "artifacts": {
    "srt": {
    "url": "https://cdn.omnapi.com/...",
    "expiresAt": "2026-07-12T00:00:00.000Z",
    "retentionDays": 7
    },
    "json": {
    "url": "https://cdn.omnapi.com/...",
    "expiresAt": "2026-07-12T00:00:00.000Z",
    "retentionDays": 7
    },
    "srtUrl": "https://cdn.omnapi.com/...",
    "jsonUrl": "https://cdn.omnapi.com/..."
    },
    "warnings": []
    }

    Current extraction returns line-level timing. timeline.words is included for a stable response shape and may be empty.


    MV Fast and Studio use the same Subtitle Sync capability when a request enables subtitles but does not provide srtUrl.

    {
    "mode": "fast",
    "source": {
    "type": "audio",
    "audioUrl": "https://example.com/song.mp3"
    },
    "subtitles": true,
    "subtitle": {
    "mode": "auto",
    "language": "auto",
    "maxCostUsdPerMin": 0.05,
    "fallback": "continue_without_subtitles"
    }
    }

    Use subtitle.mode="provided" when your product requires caller-supplied timing only. Use subtitle.mode="off" to disable subtitles even if a legacy subtitles toggle is present.


    CodeHTTPMeaning
    SUBTITLE_BUDGET_EXCEEDED400Active public subtitle price is above budget.maxCostUsdPerMin.
    AUDIO_DURATION_INVALID400source.durationSec is outside the subtitle extraction range or does not match the probed duration.
    AUDIO_DURATION_PROBE_FAILED400OmnAPI could not determine duration from the submitted audio.
    AUDIO_FILE_TOO_LARGE413Submitted audio exceeds the Subtitle Sync audio size limit.
    AUDIO_URL_INVALID400The audio URL is invalid, private/local, or otherwise not allowed.
    AUDIO_URL_UNREACHABLE400 / 408 / 502OmnAPI could not fetch or inspect the audio URL.
    SERVICE_UNAVAILABLE503Subtitle Sync is disabled, temporarily unavailable, or all extraction slots are busy.
    SUBTITLE_FILE_INVALID400A supplied subtitle file could not be parsed into usable cues.
    SUBTITLE_GENERATION_FAILED400 / 502Audio download, transcription, or subtitle artifact generation failed.
    SUBTITLE_NO_SPEECH_DETECTED422The audio did not produce usable lyric or speech content.