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

$
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

$
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

$
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

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:

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

Response

1
{
2
  "success": true,
3
  "item": {
4
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
5
    "text": null,
6
    "words": null,
7
    "query": "Summarize the main points",
8
    "answer": null,
9
    "status": "pending",
10
    "privacy_mode": false,
11
    "file_url": "https://...",
12
    "duration_seconds": null,
13
    "created_at": "2024-01-15T10:30:00Z",
14
    "updated_at": "2024-01-15T10:30:00Z"
15
  }
16
}

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:

1
// success
2
{ "success": true, "item": { "uuid": "...", "text": "...", "words": [...], "status": "completed", ... } }
3
4
// failure
5
{ "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:

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

$
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 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.