# Transcribe media

`POST https://api.vidmoat.com/v1/ai/transcriptions`

- Scope: `ai.transcribe`
- Cost: 10 cr / 5 min

Word-level timings for captions. Feed words[] straight into an addCaptions command.

> **Note.** Priced per 5 minutes of media, rounded up (so at least 10 credits), and the length is measured before any work starts: anything over 30 minutes is refused with a 400 rather than transcribed and billed. Passing `script` + `duration` instead of `src` needs no provider and is free. Works on every plan.

### Body

- `src` (string, optional): A public http(s) URL, or one of your upload URLs or filenames. Required unless you send `script`.
- `language` (string, optional): Language code, for example `en`.
- `script` (string, optional): Free mode: text to spread evenly over `duration`. No provider is called.
- `duration` (number, optional): Free mode: seconds to spread `script` over.
- `start` (number, optional, default `0`): Free mode: offset of the first word.

## Response

Returns `200`.

### Response fields

- `words` (array): `{ text, start, end }` per word, in seconds.
- `provider` (string): Which engine answered (`script` in free mode).
- `mediaSeconds` (number): The measured length that was billed.
- `credits` (object): `{ charged, remaining, basis }`.

> **Tip: With a test key.** Test keys return a fixed nine-word sample transcript and spend nothing. Free mode (`script`) returns real output on any key.

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | Neither `src` nor `script` + `duration`; a refused URL; unreadable media; or media longer than 30 minutes (`mediaSeconds`, `maxSeconds`). |
| 402 | [`insufficient_credits`](https://developer.vidmoat.com/developer/docs/errors#insufficient_credits) | The balance cannot cover the call. Nothing ran. `remaining` is the balance. |
| 501 | [`not_configured`](https://developer.vidmoat.com/developer/docs/errors#not_configured) | No speech-to-text provider is available. Nothing is charged. |
| 502 | [`provider_error`](https://developer.vidmoat.com/developer/docs/errors#provider_error) | The generation provider failed. The charge is refunded. |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/ai/transcriptions \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"src":"https://example.com/voice.mp3","language":"en"}'
```

```js Node
const res = await fetch('https://api.vidmoat.com/v1/ai/transcriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    src: 'https://example.com/voice.mp3',
    language: 'en',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

res = requests.post(
    "https://api.vidmoat.com/v1/ai/transcriptions",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "src": "https://example.com/voice.mp3",
      "language": "en",
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "words": [{ "text": "Hello", "start": 0, "end": 0.4 }],
  "provider": "whisper",
  "mediaSeconds": 42.5,
  "credits": { "charged": 10, "remaining": 4490, "basis": "10 credits per 5 minutes of media, rounded up" }
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/generation/create-transcription
Previous: [Search stock media](https://developer.vidmoat.com/developer/docs/api/media/search-stock.md)
Next: [Generate speech](https://developer.vidmoat.com/developer/docs/api/generation/create-speech.md)
All documentation: https://developer.vidmoat.com/llms-full.txt