> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.resemble.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.resemble.ai/_mcp/server.

# Create Transcript Job

Submit audio or video for transcription. The API responds immediately with a UUID that you can poll for status updates.

## Endpoint

`POST https://app.resemble.ai/api/v2/speech-to-text`

## Input Options

### Direct Upload

```bash
curl --request POST 'https://app.resemble.ai/api/v2/speech-to-text' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'file=@/path/to/recording.mp4'
```

### Signed Token

```bash
curl --request POST 'https://app.resemble.ai/api/v2/speech-to-text' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"audio_token": "eyJ..."}'
```

### Remote URL

```bash
curl --request POST 'https://app.resemble.ai/api/v2/speech-to-text' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"url": "https://example.com/audio.wav"}'
```

## Parameters

| Parameter             | Type    | Required | Notes                                                                                                                                                                                          |
| --------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audio_token`         | string  | ❌        | Token for uploaded audio file (from secure upload).                                                                                                                                            |
| `url`                 | string  | ❌        | HTTPS URL to audio/video file.                                                                                                                                                                 |
| `file`                | file    | ❌        | Audio/video file upload.                                                                                                                                                                       |
| `query`               | string  | ❌        | Initial question to ask about the transcript.                                                                                                                                                  |
| `callback_url`        | string  | ❌        | Public HTTPS URL that receives a `POST` with the result when processing finishes. Required when `zero_retention_mode` is `true`.                                                               |
| `zero_retention_mode` | boolean | ❌        | Enable zero retention: all media and transcript content is permanently deleted after the result is delivered to your `callback_url`. `privacy_mode` is accepted as an alias. Default: `false`. |

**Note:** One of `audio_token`, `url`, or `file` must be provided. Maximum file size: 500 MB. Maximum duration: 180 minutes. URL download timeout: 30 seconds.

### Callback URL validation

Whenever a `callback_url` is provided (with or without zero retention), it must be a **public HTTPS URL**. Plain `http://` URLs and addresses that resolve to private, loopback, or link-local ranges are rejected with `400`:

```json
{ "success": false, "error": "Invalid callback_url. Must be a public HTTPS URL." }
```

## Response

```json
{
  "success": true,
  "item": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "text": null,
    "words": null,
    "query": "Summarize the main points",
    "answer": null,
    "status": "pending",
    "privacy_mode": false,
    "file_url": "https://...",
    "duration_seconds": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

**Note:** Processing is asynchronous. The `text`, `words`, and `answer` fields will be populated when transcription completes.

## Result Callbacks

If you pass a `callback_url`, Resemble POSTs the result to it once processing finishes — no polling needed. On success the body contains the full serialized transcript; on failure it contains the error:

```json
// success
{ "success": true, "item": { "uuid": "...", "text": "...", "words": [...], "status": "completed", ... } }

// failure
{ "success": false, "error": "Speech transcript processing failed" }
```

Your endpoint must respond with a `2xx` status. Non-`2xx` responses are retried up to 5 times with exponential backoff. Callback requests are sent with `Content-Type: application/json` and may include an `Authorization: Bearer <secret>` header for verification — contact support to configure a webhook secret for your account.

## Zero Retention

With `zero_retention_mode=true`, Resemble retains none of your content after processing:

1. **During processing** the audio is transcribed as usual.
2. **Immediately after transcription** (success or failure), the uploaded media and any temporary processing copies are permanently deleted — deletion is confirmed, not best-effort.
3. **The transcript is delivered once** via your `callback_url`. After a successful delivery (or once delivery retries are exhausted), the transcript content itself — text, words, speakers, answers — is permanently purged.
4. **What remains** is a content-free record (UUID, status, timestamps, `privacy_mode`, deletion timestamps) for usage and audit purposes.

Because delivery happens exactly once with no polling fallback, `callback_url` is **mandatory** in this mode:

```json
{ "success": false, "error": "Zero retention requires a callback_url." }
```

```bash
curl --request POST 'https://app.resemble.ai/api/v2/speech-to-text' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'file=@/path/to/recording.mp4' \
  -F 'zero_retention_mode=true' \
  -F 'callback_url=https://example.com/webhooks/stt'
```

After the purge, `GET` requests for the transcript return the stub (content fields are no longer present) and Intelligence questions are disabled. See [Get Transcript](/voice-generation/speech-to-text/get) for the purged response shape.

**Availability:** Zero retention is a plan feature. If it is not included in your plan or subscription, the request is rejected with `402 Payment Required` — contact sales (self-serve plans) or your account manager (enterprise) to enable it.