> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salad.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For autonomous tasks, use live SaladCloud API responses for current state, availability, quotas, models, and other dynamic values. Use current OpenAPI specifications where provided for paths, schemas, required fields, and enums. Never invent endpoints, fields, prices, availability, quotas, models, or state. Prefer API workflows over Portal steps. Read before changing and never expose credentials, signed media URLs, prompts, or sensitive outputs. Retry only safe or idempotent operations with bounded backoff, honoring Retry-After. Verify every write with a read. Stop rather than repeat an uncertain non-idempotent or billable request. AI Gateway uses an organization-specific Bearer key and live /v1/models discovery. Do not delete, cancel, stop, or reduce capacity without explicit user intent. Bind shared operation IDs to the selected product path. Treat Container Engine instances as interruptible and local state as ephemeral. Install the SaladCloud skills (npx skills add https://docs.salad.com), start from the salad skill and /agents/overview; docs MCP: https://docs.salad.com/mcp.

# Transcription API Python SDK Code Examples

*Last Updated: August 24, 2026*

Use the code samples below to quickly get started developing with the **Salad Transcription Python SDK**. For a complete
list of supported parameters and request fields, refer to the **Request Options** below and
[API Reference](https://docs.salad.com/transcription/reference/api.md).

***

## Submit a local file for transcription

```python theme={null}
from salad_cloud_transcription_sdk import SaladCloudTranscriptionSdk
from salad_cloud_transcription_sdk.models import TranscriptionRequest, TranscriptionJobInput

sdk = SaladCloudTranscriptionSdk(api_key="<YOUR_API_KEY>")

request = TranscriptionRequest(
    options=TranscriptionJobInput(
        language_code="en",
        return_as_file=False,
    ),
)

job = sdk.transcribe(
    source="<LOCAL_FILE_PATH>",
    organization_name="<ORG_NAME>",
    request=request,
    auto_poll=True
)

print("Transcript text:\n", job.output['text'])
```

## Submit a remote file for transcription

```python theme={null}
sdk = SaladCloudTranscriptionSdk(api_key="<YOUR_API_KEY>")

request = TranscriptionRequest(
    options=TranscriptionJobInput(language_code="en",return_as_file=False),
)

job = sdk.transcribe(
    source="https://example.com/audio.mp3",
    organization_name="<ORG_NAME>",
    request=request,
    auto_poll=True
)

print(job.output['text'])
```

## Poll for job status

```python theme={null}
import time
from salad_cloud_transcription_sdk import SaladCloudTranscriptionSdk
from salad_cloud_sdk.models import Status
from salad_cloud_transcription_sdk.models import TranscriptionRequest, TranscriptionJobInput

sdk = SaladCloudTranscriptionSdk(api_key="<YOUR_API_KEY>")

# Setup the request
request_object = TranscriptionRequest(
    options=TranscriptionJobInput(,
        return_as_file=False,
    ),
    metadata={"project": "example_project"}
)

job = sdk.transcribe(
    source="<FILE_PATH>",
    organization_name="<ORG_NAME>",
    request=TranscriptionRequest(
        options=TranscriptionJobInput(language_code="en")
    ),
    auto_poll=False
)

while True:
    job = sdk.get_transcription_job("<ORG_NAME>", job.id_)
    if job.status in [
        Status.SUCCEEDED.value,
        Status.FAILED.value,
        Status.CANCELLED.value,
        ]:
        break
    time.sleep(5)

if job.status == Status.SUCCEEDED.value:
    print(job.output)
```

## Use the Lite model engine

```python theme={null}
from salad_cloud_transcription_sdk import SaladCloudTranscriptionSdk
from salad_cloud_transcription_sdk.models import (
    TranscriptionEngine,
    TranscriptionRequest,
    TranscriptionJobInput
)

sdk = SaladCloudTranscriptionSdk(api_key="<YOUR_API_KEY>")

request = TranscriptionRequest(
    options=TranscriptionJobInput(
        sentence_level_timestamps=True,
    ),
)

job = sdk.transcribe(
    source="<FILE_PATH>",
    organization_name="<ORG_NAME>",
    request=request,
    engine=TranscriptionEngine.Lite,
    auto_poll=True
)
```

## Add a custom vocabulary and summary (Full engine)

```python theme={null}
request = TranscriptionRequest(
    options=TranscriptionJobInput(
        language_code="en",
        custom_vocabulary=["SaladCloud", "GPU", "transcription"],
        summarize=100  # Target ~100 words
    ),
)

job = sdk.transcribe(
    source="<FILE_PATH>",
    organization_name="<ORG_NAME>",
    request=request,
    auto_poll=True
)

print("Summary:\n", job.output['summary'])
```

## Download transcription results as a file (`return_as_file`)

When processing **large jobs** (over \~1 MB of response data), or if you prefer a **downloadable JSON file** instead of
inline results, you can set `return_as_file=True`. Even if you don’t set it, responses exceeding 1 MB will automatically
be returned as a file link.

Refer to the [Features Guide](https://docs.salad.com/transcription/how-to-guides/speech-to-text.md) and
[API Reference](https://docs.salad.com/transcription/reference/api.md) for details.

```python theme={null}
from salad_cloud_transcription_sdk import SaladCloudTranscriptionSdk
from salad_cloud_transcription_sdk.models import TranscriptionRequest, TranscriptionJobInput

sdk = SaladCloudTranscriptionSdk(api_key="<YOUR_API_KEY>")

# Configure the job to return the transcription as a file URL
request = TranscriptionRequest(
    options=TranscriptionJobInput(
        language_code="en",
        return_as_file=True,  # Force output as file
    ),
    metadata={"project": "file_download_example"},
)

job = sdk.transcribe(
    source="<FILE_PATH>",
    organization_name="<ORG_NAME>",
    request=request,
    auto_poll=True
)

# The job output will contain a signed Salad S4 URL
print("Download your transcription from:", job.output['url'])
```

## Request Options

Below is a list of parameters supported by the Python SDK’s `TranscriptionJobInput`. For full details, refer to the
[API Reference](https://docs.salad.com/transcription/reference/api.md).

### `return_as_file` (bool)

Set to `"True"` to receive the transcription output as a **downloadable file URL** (useful for large responses).
Default: `"False"`, which returns the transcription inline in the API response.

> **Note:** If the response exceeds **1 MB**, it will *always* be returned as a file link, even if `return_as_file` is
> `False`.

### `language_code` (str)

Transcription supports multiple. The SDK auto-detects the source language, but specifying might improve accuracy.

### `translate` (str)

Enables **translation to English** by setting:

```python theme={null}
translate="to_eng"
```

When translation is enabled: Original transcription is not returned. Other features (timestamps, SRT, diarization) can
still be combined.

### sentence\_level\_timestamps (bool)

Returns timestamps per sentence. Default: false.

### word\_level\_timestamps (bool)

Returns timestamps per word. Default: false.

### diarization (bool)

Enables speaker separation and identification at the word level. Default: false.

### sentence\_diarization (bool)

Adds speaker attribution per sentence. Default: false.

### srt (bool)

Generates srt captions for use as subtitles. Default: false.

### summarize (int)

Returns a summary of the transcription, capped at the specified number of words. Available in Full model engine only.
Default: 0 (no summary).

### llm\_translation (list of TranslationLanguage)

Uses the built-in LLM to translate the transcription into multiple target languages. Supported languages: English,
French, German, Italian, Portuguese, Hindi, Spanish, Thai. Available in Full model engine only.

### srt\_translation (list of TranslationLanguage)

Uses the LLM to translate the generated SRT captions into multiple target languages (same languages as llm\_translation).
Available in Full model engine only.

### custom\_vocabulary (str)

Comma-separated list of domain-specific terms or phrases to improve recognition accuracy. Currently in preview.
Available in Full model engine only.

### custom\_prompt (str)

Custom prompt to guide the LLM in generating summaries, insights, or other LLM-powered outputs. Available in Full model
engine only.

```python theme={null}
custom_prompt="what is the text about?"
```

### multichannel (bool)

Preserves separate audio channels for channel-based diarization. Available in the Full model engine only. Default:
false.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.