---
title: "Create a transcribe job (audio → SRT)"
method: POST
path: "/v1/transcribe"
---

# Create a transcribe job (audio → SRT)

`POST /v1/transcribe`

## Request

- Base URL: `https://api.ffmpeg-micro.com`
- URL: `https://api.ffmpeg-micro.com/v1/transcribe`
- Auth: HTTP bearer

Generate an SRT subtitle file from an audio or video URL using Whisper. Returns a short acknowledgement with `status=pending`; poll `GET /v1/transcribe/{id}` until `status` is `completed`, then fetch the SRT via `GET /v1/transcribe/{id}/download`.
The resulting SRT is stored in your user-namespaced output bucket and can be referenced inside a transcode `subtitles=` filter to burn captions into a video (see the docs for the zoom+captions tutorial).

## Request body

- CreateTranscribeRequest
  - `media_url` string, required: GCS URL (gs://bucket/object) from a presigned upload, or a public HTTP(S) URL. The referenced file can be audio or video — only the audio track is used.
  - `language` string: BCP-47 language code hint (e.g. "en", "es"). Auto-detected when omitted.
  - `task` 'transcribe' | 'translate': "transcribe" keeps the source language; "translate" outputs English regardless of source language.

## Response `201`

Transcribe job created

- TranscribeCreated: Acknowledgement returned by `POST /v1/transcribe` — a subset of the full Transcribe resource. Poll `GET /v1/transcribe/{id}` for the full shape.
  - `id` string, uuid, required
  - `status` 'pending', required: New transcribe jobs always start as `pending`
  - `media_url` string, required: GCS URL of the source audio/video (echoed from the request)
  - `output_format` 'srt', required
  - `created_at` string, date-time, required

## Other responses

- `400`: Invalid input (missing or invalid `media_url`)
- `401`: Missing/invalid API key
- `402`: The account is fully capped: zero plan minutes remaining AND a zero token balance, so no job of any size can run until the plan renews, the plan is upgraded, or tokens are topped up. Returned synchronously instead of a `201` — no processing is attempted. A job record IS still created (visible in job listings with `status: failed`), and its id is returned so the blocked attempt can be inspected. Automations should treat `402` as terminal for the billing period and STOP retrying: the same request will keep returning `402` until the account's quota state changes. Partially-capped accounts (some minutes or tokens remaining) still return `201`, with any quota failure reported asynchronously on the job's `status`/`error_message`.
- `500`: Unexpected error

---

[API](https://skmtc.dev/ffmpeg-micro/apis/ffmpeg-micro-api.md) · [All operations](https://skmtc.dev/ffmpeg-micro/apis/ffmpeg-micro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ffmpeg-micro/apis/ffmpeg-micro-api/revisions/64bb930ff345?raw)