---
title: "Transcribe media"
method: POST
path: "/ai/transcriptions"
tags: ["Generation"]
---

# Transcribe media

`POST /ai/transcriptions`

## Request

- Base URL: `https://api.vidmoat.com/v1`
- URL: `https://api.vidmoat.com/v1/ai/transcriptions`
- Auth: HTTP bearer

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

Priced per 5 minutes of media, rounded up (so at least 5 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.

## Request body

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

## Response `200`

Transcribe media

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

## Other responses

- `400`: `invalid_request`: Neither `src` nor `script` + `duration`; a refused URL; unreadable media; or media longer than 30 minutes (`mediaSeconds`, `maxSeconds`).
- `402`: `insufficient_credits`: The balance cannot cover the call. Nothing ran. `remaining` is the balance.
- `501`: `not_configured`: No speech-to-text provider is available. Nothing is charged.
- `502`: `provider_error`: The generation provider failed. The charge is refunded.

---

[API](https://skmtc.dev/vidmoat/apis/vidmoat-api.md) · [All operations](https://skmtc.dev/vidmoat/apis/vidmoat-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vidmoat/apis/vidmoat-api/revisions/23e24e25c756?raw)