# Subtitle API
> Work with subtitle and caption files — parse, convert and re-sync, entirely locally. The parse endpoint reads SubRip (.srt) or WebVTT (.vtt) text into clean, structured cues — index, start, end (as both HH:MM:SS,mmm timecodes and milliseconds), duration and the cue text (multi-line preserved) — auto-detecting which format you sent. The convert endpoint converts between SRT and WebVTT, getting the details right: the timestamp separator (comma for SRT, dot for WebVTT), adding or removing the WEBVTT header, and renumbering cues. The shift endpoint moves every timestamp by an offset in milliseconds, positive or negative, to fix a track that runs early or late, clamping at zero so nothing goes negative. Everything is computed locally and deterministically, so it is instant and private — your media files never leave the request. Ideal for video and streaming pipelines, caption editors and players, localization and translation workflows, accessibility, and fixing out-of-sync subtitles. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. This handles subtitle files; for SMPTE video timecode (HH:MM:SS:FF) use a timecode API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/subtitle-api/..."
```

## Pricing
- **Free** (Free) — 4,535 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 14,050 calls/Mo, 8 req/s
- **Pro** ($26/Mo) — 191,500 calls/Mo, 20 req/s
- **Mega** ($64/Mo) — 1,000,000 calls/Mo, 50 req/s

## Endpoints

### Subtitle

#### `GET /v1/convert` — Convert SRT/VTT

**Parameters:**
- `subtitle` (query, required, string) — The subtitle text Example: `1
00:00:01,000 --> 00:00:04,000
Hello`
- `to` (query, optional, string) — 'srt' or 'vtt' (default: the other format) Example: `vtt`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/subtitle-api/v1/convert?subtitle=1%0A00%3A00%3A01%2C000+--%3E+00%3A00%3A04%2C000%0AHello&to=vtt"
```

**Response:**
```json
{
    "data": {
        "to": "vtt",
        "from": "srt",
        "count": 1,
        "subtitle": "WEBVTT\n\n00:00:01.000 --> 00:00:04.000\nHello\n"
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:20.586Z",
        "request_id": "10b99080-8a5b-4cfc-9be0-93038a83b1e5"
    },
    "status": "ok",
    "message": "Convert SRT/VTT",
    "success": true
}
```

#### `GET /v1/parse` — Parse a subtitle file

**Parameters:**
- `subtitle` (query, required, string) — The .srt or .vtt file text Example: `1
00:00:01,000 --> 00:00:04,000
Hello world`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/subtitle-api/v1/parse?subtitle=1%0A00%3A00%3A01%2C000+--%3E+00%3A00%3A04%2C000%0AHello+world"
```

**Response:**
```json
{
    "data": {
        "cues": [
            {
                "end": "00:00:04,000",
                "text": "Hello world",
                "index": 1,
                "start": "00:00:01,000",
                "end_ms": 4000,
                "start_ms": 1000,
                "duration_ms": 3000
            }
        ],
        "count": 1,
        "format": "srt"
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:20.654Z",
        "request_id": "f1597329-d875-4705-97e5-0828827585fd"
    },
    "status": "ok",
    "message": "Parse a subtitle file",
    "success": true
}
```

#### `GET /v1/shift` — Shift subtitle timing

**Parameters:**
- `subtitle` (query, required, string) — The subtitle text Example: `1
00:00:01,000 --> 00:00:04,000
Hi`
- `offset` (query, required, string) — Milliseconds to shift (negative = earlier) Example: `2500`
- `to` (query, optional, string) — Output format (default: keep input format)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/subtitle-api/v1/shift?subtitle=1%0A00%3A00%3A01%2C000+--%3E+00%3A00%3A04%2C000%0AHi&offset=2500"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "format": "srt",
        "subtitle": "1\n00:00:03,500 --> 00:00:06,500\nHi\n",
        "offset_ms": 2500
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:20.765Z",
        "request_id": "d15af992-e642-4431-87aa-ca257771c6d3"
    },
    "status": "ok",
    "message": "Shift subtitle timing",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/subtitle-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "Subtitle API",
        "notes": "Auto-detects SRT vs WebVTT. SRT uses HH:MM:SS,mmm and numbered cues; WebVTT uses HH:MM:SS.mmm under a WEBVTT header. Shifting clamps negative times to zero. This handles subtitle files — for SMPTE video timecode use a timecode API. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/parse",
                "params": {
                    "subtitle": "the .srt or .vtt file text (required)"
                },
                "returns": "the parsed cues with times in HH:MM:SS,mmm and milliseconds"
            },
            {
                "path": "/v1/convert",
                "params": {
                    "to": "'srt' or 'vtt' (default: the other format)",
                    "subtitle": "the subtitle text (required)"
                },
                "returns": "the converted subtitle text"
            },
            {
                "path": "/v1/shift",
                "params": {
                    "to": "output format (default: keep the input format)",
                    "offset": "milliseconds to shift (negative to move earlier)",
                    "subtitle": "the subtitle text (required)"
                },
                "returns": "the time-shifted subtitle text"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/subtitle-api
OpenAPI spec: https://www.oanor.com/api/subtitle-api/openapi.json