# Align (`align-1`): Word timestamps for your transcript

You have the script. Get a start and end time for every word.

Align takes audio and the text you already have for it (a script, captions, lyrics, an edited transcript) and returns your words, unchanged, each with a start and end time. Use it for karaoke-style highlighting, clickable transcripts and subtitle timing without retyping anything.

Words the audio doesn't clearly contain get times between their neighbors, and `matched` tells you how much of your text was heard.

- **Price:** $0.001 per minute. Billed per second of audio, rounded up, at least one second.
- **Languages:** ~100 languages

- **Input:** An audio or video file: an https URL, a data URL, or a file in a multipart upload, up to 25 MB and 5 minutes.
- **Batch:** no, one input per call
- **Status:** live
- **Built on:** [openai/whisper-base (timestamped) + our word alignment](https://huggingface.co/openai/whisper-base), Apache-2.0, 74M

## Request

```bash
curl https://labs.greatwork.company/v1/run \
  -H "Authorization: Bearer $GWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"align-1","input":"https://labs.greatwork.company/examples/voice-note.m4a","transcript":"Hey, it's Sam. Quick update on the launch. The new pricing page is live, but the checkout button still points to the old plan. Can you fix that before three o'clock? Thanks."}'
```

Upload a local file with multipart: `curl https://labs.greatwork.company/v1/run -H "Authorization: Bearer $GWL_API_KEY" -F model=align-1 -F input=@file`

## Options

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `input` | audio (URL, data URL or upload) | yes | | An audio or video file: an https URL, a data URL, or a file in a multipart upload, up to 25 MB and 5 minutes. |
| `transcript` | string | yes |  | The words spoken in the audio, in order (up to 2,000 characters per call; split longer scripts with the audio). |
| `language` | string | no |  | Language of the speech (`en`, `es`...). Detected when omitted. |

## Output

| Field | Type | Description |
|---|---|---|
| `words` | object[] | Your words in order: `text`, `start`, `end` (seconds), `matched` (heard in the audio, or interpolated). |
| `matched` | number | Share of your words found in the audio, 0 to 1. |
| `duration` | number | Audio length in seconds. |

The response envelope is always `{"id", "object": "run", "model", "created", "output", "usage": {"units", "unit", "cost_usd", "cost_micros"}, "latency_ms"}`.

## Examples (real outputs from our servers)

### Voice note script

```json
{
  "model": "align-1",
  "input": "https://labs.greatwork.company/examples/voice-note.m4a",
  "transcript": "Hey, it's Sam. Quick update on the launch. The new pricing page is live, but the checkout button still points to the old plan. Can you fix that before three o'clock? Thanks."
}
```

```json
{
  "words": [
    {
      "text": "Hey,",
      "start": 0.24,
      "end": 0.54,
      "matched": true
    },
    {
      "text": "it's",
      "start": 0.68,
      "end": 0.96,
      "matched": true
    },
    {
      "text": "Sam.",
      "start": 0.96,
      "end": 1.34,
      "matched": true
    },
    {
      "text": "Quick",
      "start": 1.54,
      "end": 1.84,
      "matched": true
    },
    {
      "text": "update",
      "start": 1.84,
      "end": 2.1,
      "matched": true
    },
    {
      "text": "on",
      "start": 2.1,
      "end": 2.24,
      "matched": true
    },
    {
      "text": "the",
      "start": 2.24,
      "end": 2.52,
      "matched": true
    },
    {
      "text": "launch.",
      "start": 2.52,
      "end": 2.9,
      "matched": true
    },
    {
      "text": "The",
      "start": 3.04,
      "end": 3.18,
      "matched": true
    },
    {
      "text": "new",
      "start": 3.18,
      "end": 3.56,
      "matched": true
    },
    {
      "text": "pricing",
      "start": 3.56,
      "end": 3.98,
      "matched": true
    },
    {
      "text": "page",
      "start": 3.98,
      "end": 4.14,
      "matched": true
    },
    {
      "text": "is",
      "start": 4.14,
      "end": 4.34,
      "matched": true
    },
    {
      "text": "live,",
      "start": 4.34,
      "end": 4.62,
      "matched": true
    },
    {
      "text": "but",
      "start": 4.74,
      "end": 4.9,
      "matched": true
    },
    {
      "text": "the",
      "start": 4.9,
      "end": 5.22,
      "matched": true
    },
    {
      "text": "checkout",
      "start": 5.22,
      "end": 5.66,
      "matched": true
    },
    {
      "text": "button",
      "start": 5.66,
      "end": 5.9,
      "matched": true
    },
    {
      "text": "still",
      "start": 5.9,
      "end": 6.24,
      "matched": true
    },
    {
      "text": "points",
      "start": 6.24,
      "end": 6.5,
      "matched": true
    },
    {
      "text": "to",
      "start": 6.5,
      "end": 6.66,
      "matched": true
    },
    {
      "text": "the",
      "start": 6.66,
      "end": 6.88,
      "matched": true
    },
    {
      "text": "old",
      "start": 6.88,
      "end": 7.24,
      "matched": true
    },
    {
      "text": "plan.",
      "start": 7.24,
      "end": 7.58,
      "matched": true
    },
    {
      "text": "Can",
      "start": 7.8,
      "end": 7.96,
      "matched": true
    },
    {
      "text": "you",
      "start": 7.96,
      "end": 8.24,
      "matched": true
    },
    {
      "text": "fix",
      "start": 8.24,
      "end": 8.44,
      "matched": true
    },
    {
      "text": "that",
      "start": 8.44,
      "end": 8.7,
      "matched": true
    },
    {
      "text": "before",
      "start": 8.7,
      "end": 9.08,
      "matched": true
    },
    {
      "text": "three",
      "start": 9.08,
      "end": 9.72,
      "matched": false
    },
    {
      "text": "o'clock?",
      "start": 9.72,
      "end": 10.36,
      "matched": false
    },
    {
      "text": "Thanks.",
      "start": 10.36,
      "end": 10.48,
      "matched": true
    }
  ],
  "matched": 0.938,
  "duration": 10.73
}
```

7071 ms, $0.000187.

## Good for

- Highlight words as audio plays
- Time subtitles from an existing script
- Clickable, seekable transcripts
- Check a voiceover matches its script

## Limits and caveats

- Your text should match what's said; a low `matched` means the script and audio differ.
- Interpolated words get evenly spaced times, not measured ones.
