### Install Orchard Dictate Extension

Source: https://www.orchardrun.com/docs

Install the Orchard Dictate extension from the Visual Studio Marketplace using the command line.

```bash
code --install-extension Orchardrun.orchard-dictate
```

--------------------------------

### Install Orchard SDK

Source: https://www.orchardrun.com/docs

Install the official `@orchardrun/sdk` package using pnpm. This SDK simplifies HTTP requests and provides typed methods for all Orchard API endpoints.

```bash
pnpm add @orchardrun/sdk
```

--------------------------------

### Create Audio Transcription (Python)

Source: https://www.orchardrun.com/docs

Submit an audio file for transcription using a Python script. This example demonstrates how to send the audio file and specify transcription parameters.

```python
import requests

url = "https://api.orchardrun.com/v1/audio/transcriptions"
headers = {
    "Authorization": "Bearer ork_..."
}
files = {
    "file": open("audio.mp3", "rb")
}
data = {
    "language": "es",
    "response_format": "verbose_json"
}

response = requests.post(url, headers=headers, files=files, data=data)

print(response.json())
```

--------------------------------

### Cross-language Synthesis Example (cURL)

Source: https://www.orchardrun.com/docs

This example demonstrates cross-language synthesis by providing Spanish text and an American English voice. The `source_language` and `translate=force` parameters ensure the text is translated before synthesis.

```bash
# Input is Spanish, voice is American English →
# server translates to English then synthesizes with Amy.
curl -X POST https://api.orchardrun.com/v1/tts/generate \
  -H "Authorization: Bearer ork_..." \
  -F text="Hola, ¿cómo estás?" \
  -F voice_id="en_US-amy" \
  -F source_language=es \
  -F translate=force \
  --output greeting_en.wav
```

--------------------------------

### Orchard SDK Quickstart (TypeScript)

Source: https://www.orchardrun.com/docs

Perform transcription, text-to-speech synthesis, and voice cloning using the Orchard SDK. Ensure your API key is set in the environment or passed directly to the constructor.

```typescript
import Orchard from "@orchardrun/sdk";
import fs from "node:fs";

const orchard = new Orchard({ apiKey: process.env.ORCHARD_API_KEY });

// Speech to text
const { text } = await orchard.transcribe({
  file: fs.readFileSync("./call.wav"),
  language: "es",
});
console.log(text);

// Text to speech
const audio = await orchard.tts.generate({
  text: "Hola mundo",
  voice: "es_MX-claude",
});
await fs.promises.writeFile(
  "./out.wav",
  Buffer.from(await audio.arrayBuffer()),
);

// Voice cloning: register once, synth many times
const voice = await orchard.voices.create({
  name: "Mateo · founder",
  file: fs.readFileSync("./sample.wav"),
  language: "es",
});
const synth = await orchard.voices.synthesize(voice.id, {
  text: "Hola, soy Mateo.",
});
```

--------------------------------

### Create Transcription Job with Webhook

Source: https://www.orchardrun.com/docs

This example demonstrates how to create a transcription job and specify a webhook URL to receive the results upon completion. This avoids the need for polling.

```APIDOC
## POST /v1/transcriptions

### Description
Creates a new transcription job and configures a webhook to receive the results upon completion.

### Method
POST

### Endpoint
/v1/transcriptions

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the media to transcribe.
- **language** (string) - Required - The language of the media (e.g., "en").
- **webhook_url** (string) - Required - The URL to which the job results will be POSTed upon completion.

### Request Example
```json
{
  "url": "https://youtu.be/dQw4w9WgXcQ",
  "language": "en",
  "webhook_url": "https://your.n8n.instance/webhook/orchard-result"
}
```

### Response
#### Success Response (200)
- **job_id** (string) - The unique identifier for the transcription job.
- **status** (string) - The initial status of the job.
- **result** (object) - The transcription results (initially null).
- **error** (string) - Any error message (initially null).

#### Response Example
```json
{
  "job_id": "abc123...",
  "status": "processing",
  "result": null,
  "error": null
}
```
```

--------------------------------

### Vercel AI SDK Transcription with Orchard

Source: https://www.orchardrun.com/docs

Integrate Orchard's transcription capabilities with the Vercel AI SDK. This example shows how to use the `transcribe` function with Orchard's model and provider options.

```typescript
import { experimental_transcribe as transcribe } from "ai";
import { orchard } from "@orchardrun/sdk/ai-sdk";
import fs from "node:fs";

const { text, language, durationInSeconds } = await transcribe({
  model: orchard.transcription(),
  audio: fs.readFileSync("./call.wav"),
  mediaType: "audio/wav",
  providerOptions: { orchard: { language: "es" } },
});
```

--------------------------------

### List Generic TTS Voices (Python)

Source: https://www.orchardrun.com/docs

Retrieve the list of available generic TTS voices using Python. This example demonstrates how to make the API call and parse the JSON response.

```python
import requests
import json

response = requests.get("https://api.orchardrun.com/v1/tts/voices/generic")
voices = json.loads(response.text)

for voice in voices:
    print(f"Voice ID: {voice['voice_id']}, Language: {voice['language']}, Locale: {voice['locale']}, Description: {voice['description']}")
```

--------------------------------

### List Generic TTS Voices

Source: https://www.orchardrun.com/docs

Use this endpoint to get a list of available generic TTS voices. No authentication is required. This is useful for populating voice pickers in your application.

```shell
curl https://api.orchardrun.com/v1/tts/voices/generic | jq
```

--------------------------------

### Get Generic Voices

Source: https://www.orchardrun.com/docs

Fetches a list of all generic text-to-speech voices available. This endpoint is public and does not require authentication. It's useful for populating voice pickers in user interfaces.

```APIDOC
## GET /v1/tts/voices/generic

### Description
Retrieves a list of all generic text-to-speech voices available out-of-the-box.

### Method
GET

### Endpoint
/v1/tts/voices/generic

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
Returns an array of objects, where each object contains the following fields:
- **voice_id** (string) - The unique identifier for the voice.
- **language** (string) - The ISO 639-1 language code.
- **locale** (string) - The locale code (e.g., `es_MX`).
- **flag** (string) - A flag representing the voice's origin.
- **gender** (string) - The gender of the voice (Male/Female).
- **description** (string) - A description of the voice's characteristics.

#### Response Example
```json
[
  {
    "voice_id": "en_US-amy",
    "language": "en",
    "locale": "en_US",
    "flag": "🇺🇸",
    "gender": "Female",
    "description": "friendly, conversational"
  },
  {
    "voice_id": "en_US-ryan",
    "language": "en",
    "locale": "en_US",
    "flag": "🇺🇸",
    "gender": "Male",
    "description": "professional, narration"
  }
]
```
```

--------------------------------

### Handle Typed Orchard Errors

Source: https://www.orchardrun.com/docs

Catch specific `OrchardError` subclasses to implement retry logic or guide users. This example demonstrates handling rate limit, quota, and authentication errors.

```typescript
import {
  OrchardRateLimitError,
  OrchardQuotaError,
  OrchardAuthError,
} from "@orchardrun/sdk";

try {
  await orchard.tts.generate({ text, voice });
} catch (e) {
  if (e instanceof OrchardRateLimitError) {
    await sleep((e.retryAfterSeconds ?? 5) * 1000);
    return retry();
  }
  if (e instanceof OrchardQuotaError) {
    // 402 — out of balance. Surface upgrade CTA to your user.
    return showUpgradeBanner();
  }
  if (e instanceof OrchardAuthError) {
    // 401/403 — rotate the API key.
    return null;
  }
  throw e;
}
```

--------------------------------

### Cancel Long Transcriptions with AbortSignal

Source: https://www.orchardrun.com/docs

Implement a cancellation mechanism for long-running transcription tasks using `AbortSignal`. This example sets a 5-second hard cap on the transcription process.

```typescript
const ac = new AbortController();
setTimeout(() => ac.abort(), 5_000); // 5-second hard cap

await orchard.transcribe(
  { file: bigAudioBuffer, language: "es" },
  { signal: ac.signal },
);
```

--------------------------------

### GET /v1/voices · list + quota

Source: https://www.orchardrun.com/docs

Retrieves a list of all cloned voices and the current quota usage. This endpoint helps manage cloned voices and understand remaining capacity.

```APIDOC
## GET /v1/voices · list + quota

### Description
Retrieves a list of all cloned voices and the current quota usage. This endpoint helps manage cloned voices and understand remaining capacity.

### Method
GET

### Endpoint
https://api.orchardrun.com/v1/voices

### Response
#### Success Response
Returns `{ voices: [...], quota: { used: 2, limit: 3 } }`. The quota block lets you render an "X of Y used" UI without an extra round-trip.
```

--------------------------------

### Poll Transcription Job Status

Source: https://www.orchardrun.com/docs

Poll this endpoint using the job ID to get the current status, progress, and eventually the transcription results. The response includes a progress snapshot while running and the full result upon success.

```curl
curl https://api.orchardrun.com/v1/transcriptions/abc123 \
  -H "Authorization: Bearer ork_..."
```

--------------------------------

### POST /v1/voices · create from audio

Source: https://www.orchardrun.com/docs

Uploads a reference recording to create a new voice. This is a one-time compute process that persists the voice. The engine used (Premium or Multilingual) is determined by the reference audio's language.

```APIDOC
## POST /v1/voices · create from audio

### Description
Uploads a reference recording to create a new voice. This is a one-time compute process that persists the voice. The engine used (Premium or Multilingual) is determined by the reference audio's language.

### Method
POST

### Endpoint
https://api.orchardrun.com/v1/voices

### Parameters
#### Form fields
- **audio** (file) - Required - Reference audio: 6-60 s, any codec ffmpeg decodes (wav/webm/m4a/mp3). Normalised server-side to 24 kHz mono PCM.
- **name** (string) - Required - 1-80 chars. Shown in the playground voice list + the rename endpoint can change it later.
- **language** (string) - Required - ISO 639-1 of the reference: es / en / pt / fr / de / it / pl / tr / ru / nl / cs / ar / zh-cn / ja / hu / ko / hi. Drives engine routing (es → Premium, else Multilingual).

### Response
#### Success Response (201 Created)
Returns JSON with `id`, `name`, `language`, `tier` (`"premium-es"` or `"multilingual"`), `embed_bytes`, `created_at`.

#### Error Response (402)
Returned when you've hit your plan's cloned-voice quota. Delete an existing voice or upgrade your plan.
```

--------------------------------

### Text-to-Speech Synthesis (SDK)

Source: https://www.orchardrun.com/docs

Synthesize text to audio across 17 languages using the TypeScript SDK.

```APIDOC
## orchard.tts.generate()

### Description
Synthesizes text into speech.

### Method Signature
`tts.generate(options: { text: string; voice: string; })`

### Parameters
- **text** (string) - Required - The text to synthesize.
- **voice** (string) - Required - The voice to use for synthesis (e.g., 'es_MX-claude').

### Request Example
```typescript
import Orchard from "@orchardrun/sdk";

const orchard = new Orchard({ apiKey: process.env.ORCHARD_API_KEY });

const audio = await orchard.tts.generate({
  text: "Hola mundo",
  voice: "es_MX-claude",
});
await fs.promises.writeFile(
  "./out.wav",
  Buffer.from(await audio.arrayBuffer()),
);
```
```

--------------------------------

### Create a Cloned Voice

Source: https://www.orchardrun.com/docs

Use this endpoint to upload a reference audio file and create a new cloned voice. The audio should be 6-60 seconds long. The language parameter determines the engine used for processing.

```curl
curl -X POST https://api.orchardrun.com/v1/voices \
  -H "Authorization: Bearer $ORCHARD_KEY" \
  -F "audio=@reference.wav" \
  -F "name=My voice" \
  -F "language=es"
```

```python
import requests

api_key = "$ORCHARD_KEY"
url = "https://api.orchardrun.com/v1/voices"

with open("reference.wav", "rb") as audio_file:
    files = {"audio": audio_file}
    data = {"name": "My voice", "language": "es"}
    headers = {"Authorization": f"Bearer {api_key}"}

    response = requests.post(url, files=files, data=data, headers=headers)

print(response.json())
```

--------------------------------

### Download Transcription Results in Various Formats

Source: https://www.orchardrun.com/docs

Download the transcription results for a completed job in the specified format. The response includes a `Content-Disposition: attachment` header.

```curl
# Plain text
curl "https://api.orchardrun.com/v1/transcriptions/abc123/download?format=text" \
  -H "Authorization: Bearer ork_..." -O
```

```curl
# SRT subtitles
curl "https://api.orchardrun.com/v1/transcriptions/abc123/download?format=srt" \
  -H "Authorization: Bearer ork_..." -O
```

```curl
# Markdown with YAML frontmatter
curl "https://api.orchardrun.com/v1/transcriptions/abc123/download?format=md" \
  -H "Authorization: Bearer ork_..." -O
```

--------------------------------

### Convert WAV to Opus using ffmpeg

Source: https://www.orchardrun.com/docs

Convert a WAV audio file to a more efficient Opus format before uploading to reduce file size and upload time. This is useful for long audio files.

```bash
# Convert before upload
ffmpeg -i recording.wav -c:a libopus -b:a 32k recording.opus
# 27 MB → ~2 MB. Then upload normally.
```

--------------------------------

### Send Job with Webhook URL (cURL)

Source: https://www.orchardrun.com/docs

Use this cURL command to create a transcription job and specify a `webhook_url` where the results should be sent upon completion. Ensure your `Authorization` header is correctly set.

```curl
curl -X POST https://api.orchardrun.com/v1/transcriptions \
  -H "Authorization: Bearer ork_..." \
  -H "Content-Type: application/json" \
  -d '{ \
    "url": "https://youtu.be/dQw4w9WgXcQ", \
    "language": "en", \
    "webhook_url": "https://your.n8n.instance/webhook/orchard-result" \
  }'
```

--------------------------------

### Transcribe Audio using cURL

Source: https://www.orchardrun.com/docs

Use this cURL command to transcribe an audio file asynchronously. Specify the audio file, language, and desired response format.

```bash
curl -X POST https://api.orchardrun.com/v1/audio/transcriptions \
  -H "Authorization: Bearer ork_..." \
  -F file=@audio.mp3 \
  -F language=es \
  -F response_format=verbose_json
```

--------------------------------

### Voice Cloning (SDK)

Source: https://www.orchardrun.com/docs

Clone a voice from a reference audio sample using the TypeScript SDK.

```APIDOC
## orchard.voices.create() and orchard.voices.synthesize()

### Description
Clones a voice from a reference audio sample and synthesizes speech using the cloned voice.

### Method Signatures
`voices.create(options: { name: string; file: Buffer; language: string; })`
`voices.synthesize(voiceId: string, options: { text: string; })`

### Parameters for `create`
- **name** (string) - Required - A name for the cloned voice (e.g., 'Mateo · founder').
- **file** (Buffer) - Required - The audio file containing the voice sample (6-60s).
- **language** (string) - Required - The language of the voice sample (e.g., 'es').

### Parameters for `synthesize`
- **voiceId** (string) - Required - The ID of the cloned voice.
- **text** (string) - Required - The text to synthesize using the cloned voice.

### Request Example
```typescript
import Orchard from "@orchardrun/sdk";
import fs from "node:fs";

const orchard = new Orchard({ apiKey: process.env.ORCHARD_API_KEY });

// Voice cloning: register once, synth many times
const voice = await orchard.voices.create({
  name: "Mateo · founder",
  file: fs.readFileSync("./sample.wav"),
  language: "es",
});
const synth = await orchard.voices.synthesize(voice.id, {
  text: "Hola, soy Mateo.",
});
```
```

--------------------------------

### Synthesize Audio from a Cloned Voice

Source: https://www.orchardrun.com/docs

Generate audio using a previously cloned voice. Provide the text to be synthesized and the language. The output is a WAV audio file. This action debits from your per-second balance.

```curl
curl -X POST https://api.orchardrun.com/v1/voices/$VOICE_ID/synthesize \
  -H "Authorization: Bearer $ORCHARD_KEY" \
  -F "text=Hola mundo, esta es mi voz clonada." \
  -F "language=es" \
  --output out.wav
```

```python
import requests

api_key = "$ORCHARD_KEY"
voice_id = "$VOICE_ID"
url = f"https://api.orchardrun.com/v1/voices/{voice_id}/synthesize"

data = {"text": "Hola mundo, esta es mi voz clonada.", "language": "es"}
headers = {"Authorization": f"Bearer {api_key}"}

response = requests.post(url, data=data, headers=headers, stream=True)

with open("out.wav", "wb") as audio_file:
    for chunk in response.iter_content(chunk_size=8192):
        audio_file.write(chunk)
```

--------------------------------

### Transcription (SDK)

Source: https://www.orchardrun.com/docs

Transcribe audio to text using the TypeScript SDK.

```APIDOC
## orchard.transcribe()

### Description
Transcribes audio to text using the SDK.

### Method Signature
`transcribe(options: { file: Buffer; language: string; })`

### Parameters
- **file** (Buffer) - Required - The audio file to transcribe.
- **language** (string) - Required - The language of the audio (e.g., 'es').

### Request Example
```typescript
import Orchard from "@orchardrun/sdk";
import fs from "node:fs";

const orchard = new Orchard({ apiKey: process.env.ORCHARD_API_KEY });

// Speech to text
const { text } = await orchard.transcribe({
  file: fs.readFileSync("./call.wav"),
  language: "es",
});
console.log(text);
```
```

--------------------------------

### Download Transcription Results

Source: https://www.orchardrun.com/docs

Download the transcription results in a specified format. Returns the file with a Content-Disposition attachment header.

```APIDOC
## GET /v1/transcriptions/{id}/download · formatted

### Description
Download the transcription results in a specified format. Returns the file with a Content-Disposition attachment header.

### Method
GET

### Endpoint
/v1/transcriptions/{id}/download

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the transcription job.

#### Query Parameters
- **format** (string) - Required - The desired output format (e.g., "text", "srt", "md").

### Response
#### Success Response (200 OK)
Returns the transcription content in the specified format as a file attachment.
```

--------------------------------

### Synthesize Text-to-Speech

Source: https://www.orchardrun.com/docs

Generates a WAV audio file from input text using a specified voice. The request is synchronous and the response body contains the raw audio data.

```APIDOC
## POST /v1/tts/generate

### Description
Synthesizes speech from the provided text using a specified voice ID. The API returns a WAV audio file directly in the response body. This is a synchronous operation.

### Method
POST

### Endpoint
https://api.orchardrun.com/v1/tts/generate

### Parameters
#### Form fields
- **text** (string) - required - max 500 chars - The text to be spoken. Punctuation and capitalization affect prosody. For longer texts, split into chunks of 500 characters or less and concatenate the resulting WAV files client-side.
- **voice_id** (string) - required - The identifier for the voice to use (e.g., "en_US-amy", "es_MX-claude"). The language of the voice is determined by this ID.
- **voice_type** (string) - optional - Defaults to "generic". Use "generic" for the public voice library. Voice cloning is not exposed in this version.
- **source_language** (string) - optional - An ISO 639-1 code that provides a language hint for the input text, especially when it differs from the voice's language. If provided and different from the voice language, the text will be auto-translated before synthesis.
- **translate** (string) - optional - Defaults to "auto". Controls the translation policy: "auto" (translate only when source_language differs from voice language), "force" (always translate), "off" (synthesize the literal text using the voice's phoneme set, even if mismatched).

### Request Example
```curl
curl -X POST https://api.orchardrun.com/v1/tts/generate \
  -H "Authorization: Bearer ork_..." \
  -F text="Hola, ¿qué tal todo por allá?" \
  -F voice_id="es_MX-claude" \
  -F voice_type="generic" \
  --output out.wav
```

### Response
#### Success Response (200 OK)
- **Content-Type**: audio/wav - The response body is the raw 22.05 kHz / 16-bit mono WAV audio file.

#### Error Responses
- **404** - If the `voice_id` is unknown.
- **402** - If the user's balance is exhausted.
- **429** - If the concurrent request limit for the plan is exceeded.
```

--------------------------------

### Webhook Retry and Idempotency

Source: https://www.orchardrun.com/docs

Details on Orchard's retry mechanism for webhook deliveries and how to handle idempotency using the `X-Orchard-Job-Id` header.

```APIDOC
## Retry & Idempotency

### Description
Understand how Orchard handles delivery failures and how to ensure your endpoint processes webhook notifications exactly once.

### Retry Policy
- Orchard attempts delivery up to 3 times with exponential backoff (1s, 5s, 25s).
- A `2xx` response from your endpoint signifies success, and retries will stop.
- A `4xx` response indicates a permanent failure; Orchard will not retry.
- `5xx` responses or network errors trigger retries up to the maximum of 3 attempts.

### Idempotency
- Use the `X-Orchard-Job-Id` header to deduplicate incoming requests. The same `job_id` may arrive more than once, especially in retry scenarios.
```

--------------------------------

### Authenticate with JWT

Source: https://www.orchardrun.com/docs

Use a JWT for authentication, typically obtained via the login endpoint. This method is used by the web dashboard.

```text
Authorization: Bearer eyJhbGciOi...
```

--------------------------------

### Audio Transcription (HTTP)

Source: https://www.orchardrun.com/docs

Transcribe audio to text in 60+ languages using the HTTP API.

```APIDOC
## POST /v1/audio/transcriptions

### Description
Transcribes audio to text.

### Method
POST

### Endpoint
https://api.orchardrun.com/v1/audio/transcriptions

### Parameters
#### Form Data
- **file** (file) - Required - The audio file to transcribe.
- **language** (string) - Optional - The language of the audio (e.g., 'es').
- **response_format** (string) - Optional - The desired format for the response (e.g., 'verbose_json').

### Request Example
```
curl -X POST https://api.orchardrun.com/v1/audio/transcriptions \
  -H "Authorization: Bearer ork_..." \
  -F file=@audio.mp3 \
  -F language=es \
  -F response_format=verbose_json
```
```

--------------------------------

### Authenticate with API Key

Source: https://www.orchardrun.com/docs

Use an API key for programmatic access to the Orchard Run API. The key can be sent in the Authorization header as a Bearer token or in the X-API-Key header.

```text
Authorization: Bearer ork_...
 or
X-API-Key: ork_...
```

--------------------------------

### Generate Speech from Text (cURL)

Source: https://www.orchardrun.com/docs

Use this cURL command to send a POST request to the TTS API, providing the text and voice ID to generate a WAV audio file. The response body directly contains the audio data.

```bash
curl -X POST https://api.orchardrun.com/v1/tts/generate \
  -H "Authorization: Bearer ork_..." \
  -F text="Hola, ¿qué tal todo por allá?" \
  -F voice_id="es_MX-claude" \
  -F voice_type="generic" \
  --output out.wav
```

--------------------------------

### List Cloned Voices and Quota

Source: https://www.orchardrun.com/docs

Retrieve a list of all cloned voices associated with your account and your current usage quota. This helps in managing your cloned voice limit.

```curl
curl https://api.orchardrun.com/v1/voices \
  -H "Authorization: Bearer $ORCHARD_KEY"
```

--------------------------------

### Submit Transcription Job via File Upload

Source: https://www.orchardrun.com/docs

Submit a transcription job by uploading an audio file. This returns a job ID and initial status.

```APIDOC
## POST /v1/transcriptions/upload · file

### Description
Submit a transcription job by uploading an audio file. This returns a job ID and initial status.

### Method
POST

### Endpoint
/v1/transcriptions/upload

### Parameters
#### Form Data
- **file** (file) - Required - The audio file to transcribe.
- **language** (string) - Required - The language of the audio.

### Response
#### Success Response (202 Accepted)
- **job_id** (string) - The ID of the submitted job.
- **status** (string) - The initial status of the job (e.g., "queued").

### Response Example
```json
{
  "job_id": "...",
  "status": "queued"
}
```
```

--------------------------------

### POST /v1/voices/{id}/synthesize · generate audio

Source: https://www.orchardrun.com/docs

Generates audio from a cloned voice. This endpoint synthesizes speech from cached voice data based on the provided text and language. It debits from a shared per-second balance.

```APIDOC
## POST /v1/voices/{id}/synthesize · generate audio

### Description
Generates audio from a cloned voice. This endpoint synthesizes speech from cached voice data based on the provided text and language. It debits from a shared per-second balance.

### Method
POST

### Endpoint
https://api.orchardrun.com/v1/voices/$VOICE_ID/synthesize

### Parameters
#### Form fields
- **text** (string) - Required - 1-500 chars.
- **language** (string) - Required - Same set as create. Multilingual voices can synthesize cross-lingually (your English voice speaking Italian); Premium ES voices stay in Spanish.

### Response
#### Success Response
Returns `audio/wav` bytes (16-bit PCM, 24 kHz mono).
```

--------------------------------

### Submit Transcription Job via File Upload

Source: https://www.orchardrun.com/docs

Use this endpoint to upload an audio file for transcription. The API returns a job ID to poll for status updates.

```curl
curl -X POST https://api.orchardrun.com/v1/transcriptions/upload \
  -H "Authorization: Bearer ork_..." \
  -F file=@interview.mp3 \
  -F language=es
```

--------------------------------

### Submit Transcription Job via YouTube URL

Source: https://www.orchardrun.com/docs

Submit a transcription job for a YouTube URL. This returns a job ID and initial status.

```APIDOC
## POST /v1/transcriptions · YouTube URL

### Description
Submit a transcription job for a YouTube URL. This returns a job ID and initial status.

### Method
POST

### Endpoint
/v1/transcriptions

### Request Body
- **url** (string) - Required - The YouTube URL to transcribe.
- **language** (string) - Required - The language of the audio.

### Request Example
```json
{
  "url": "https://youtu.be/dQw4w9WgXcQ",
  "language": "en"
}
```

### Response
#### Success Response (202 Accepted)
- **job_id** (string) - The ID of the submitted job.
- **status** (string) - The initial status of the job (e.g., "queued").

### Response Example
```json
{
  "job_id": "abc123...",
  "status": "queued"
}
```
```

--------------------------------

### Submit Transcription Job via YouTube URL

Source: https://www.orchardrun.com/docs

Use this endpoint to submit a YouTube URL for transcription. The API returns a job ID to poll for status updates.

```curl
curl -X POST https://api.orchardrun.com/v1/transcriptions \
  -H "Authorization: Bearer ork_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://youtu.be/dQw4w9WgXcQ","language":"en"}'
```

--------------------------------

### Audio Transcription

Source: https://www.orchardrun.com/docs

Accepts a standard multipart upload and blocks until the cluster returns a transcript. Supports 60+ languages with automatic detection. The request and response shape follows the public transcription-API conventions.

```APIDOC
## POST /v1/audio/transcriptions

### Description
Transcribes an audio file. Supports multiple languages and response formats.

### Method
POST

### Endpoint
https://api.orchardrun.com/v1/audio/transcriptions

### Parameters
#### Request Body
- **file** (binary, required) - Audio file. Supported formats: mp3, m4a, wav, mp4, ogg, flac, webm. Max 500 MB.
- **language** (string, optional) - ISO 639-1 language code hint (e.g., es, en, pt). Auto-detected when omitted.
- **response_format** (string, optional) - Format of the response. Options: json (default), verbose_json, text.

### Request Example
```curl
curl -X POST https://api.orchardrun.com/v1/audio/transcriptions \
  -H "Authorization: Bearer ork_..." \
  -F file=@audio.mp3 \
  -F language=es \
  -F response_format=verbose_json
```

### Response
#### Success Response (200)
- The response format depends on the `response_format` parameter. For `verbose_json`, it includes detailed transcription information.
```

--------------------------------

### Webhook Headers Sent by Orchard

Source: https://www.orchardrun.com/docs

Information about the HTTP headers that Orchard includes when sending webhook notifications.

```APIDOC
## Webhook Headers

### Description
Orchard sends the following headers with its webhook POST requests to help identify and manage incoming notifications.

### Headers
- **User-Agent**: `Orchard-Webhook/1.0` - Identifies the sender as Orchard.
- **X-Orchard-Job-Id**: `string` - The same `job_id` from the initial POST request. Use this for idempotency.
- **X-Orchard-Attempt**: `number` - The current retry attempt number (1, 2, or 3).
- **Content-Type**: `application/json` - Indicates the format of the payload.
```

--------------------------------

### Webhook Payload Structure

Source: https://www.orchardrun.com/docs

This details the structure of the JSON payload that Orchard POSTs to your specified webhook URL when a transcription job is completed.

```APIDOC
## Webhook Payload

### Description
This is the structure of the JSON payload sent to your `webhook_url` upon job completion. It mirrors the structure of a successful `GET /v1/transcriptions/{id}` response.

### Payload Structure
```json
{
  "job_id": "string",         // The unique ID of the job.
  "status": "string",         // "success" or "failed".
  "result": {
    "text": "string",         // The transcribed text.
    "language": "string",     // Detected or specified language.
    "duration_seconds": "number", // Duration of the media in seconds.
    "segments": [ ... ],        // Array of transcription segments.
    "provider": "string",     // The transcription provider used.
    "model": "string",        // The transcription model used.
    "elapsed_ms": "number",     // Time taken for transcription in milliseconds.
    "post_processed": "boolean" // Indicates if post-processing was applied.
  },
  "error": "string" | null    // Error message if status is "failed", otherwise null.
}
```
```

--------------------------------

### Delete a Cloned Voice

Source: https://www.orchardrun.com/docs

Remove a cloned voice and all its associated artifacts permanently. This frees up a slot in your quota immediately. Recreating the voice will require a new reference recording.

```curl
curl -X DELETE https://api.orchardrun.com/v1/voices/$VOICE_ID \
  -H "Authorization: Bearer $ORCHARD_KEY"
```

--------------------------------

### DELETE /v1/voices/{id}

Source: https://www.orchardrun.com/docs

Deletes a cloned voice and frees up a quota slot immediately. All associated artifacts, including embedding bytes, are permanently removed.

```APIDOC
## DELETE /v1/voices/{id}

### Description
Deletes a cloned voice and frees up a quota slot immediately. All associated artifacts, including embedding bytes, are permanently removed.

### Method
DELETE

### Endpoint
https://api.orchardrun.com/v1/voices/$VOICE_ID

### Response
#### Success Response (204)
Returns `204`.
```

--------------------------------

### Orchard Webhook Payload Structure

Source: https://www.orchardrun.com/docs

This is the JSON payload structure that Orchard will POST to your specified `webhook_url` when a job finishes. It includes the job status, results, and any potential errors.

```json
{
  "job_id": "abc123...",
  "status": "success",         // or "failed"
  "result": {
    "text": "...",
    "language": "en",
    "duration_seconds": 1099,
    "segments": [ ... ],
    "provider": "local",
    "model": "orchard-stt-v1",
    "elapsed_ms": 17430,
    "post_processed": true
  },
  "error": null               // string when status="failed"
}
```

--------------------------------

### Rename a Cloned Voice

Source: https://www.orchardrun.com/docs

Update the display name of an existing cloned voice. This operation does not affect the voice embedding and avoids the need to re-record.

```curl
curl -X PATCH https://api.orchardrun.com/v1/voices/$VOICE_ID \
  -H "Authorization: Bearer $ORCHARD_KEY" \
  -F "name=My better name"
```

--------------------------------

### PATCH /v1/voices/{id} · rename

Source: https://www.orchardrun.com/docs

Renames an existing cloned voice. This operation only changes the label of the voice, leaving the underlying embedding intact. It avoids the need to delete and recreate the voice.

```APIDOC
## PATCH /v1/voices/{id} · rename

### Description
Renames an existing cloned voice. This operation only changes the label of the voice, leaving the underlying embedding intact. It avoids the need to delete and recreate the voice.

### Method
PATCH

### Endpoint
https://api.orchardrun.com/v1/voices/$VOICE_ID

### Parameters
#### Form fields
- **name** (string) - Required - The new name for the voice.
```

--------------------------------

### Poll Transcription Job Status

Source: https://www.orchardrun.com/docs

Poll for the status of a transcription job using its ID. Provides progress while running and the full result upon completion.

```APIDOC
## GET /v1/transcriptions/{id} · poll

### Description
Poll for the status of a transcription job using its ID. Provides progress while running and the full result upon completion.

### Method
GET

### Endpoint
/v1/transcriptions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the transcription job.

### Response
#### Success Response (200 OK)
- **job_id** (string) - The ID of the transcription job.
- **status** (string) - The current status of the job (e.g., "running", "success").
- **progress** (object) - Optional - Snapshot of progress while running.
  - **current_ms** (integer) - Current playback time in milliseconds.
  - **total_ms** (integer) - Total duration in milliseconds.
  - **percent** (integer) - Completion percentage.
- **result** (object) - Optional - The full transcription result once succeeded.
  - **text** (string) - The transcribed text.
  - **language** (string) - The detected language.
  - **duration_seconds** (number) - The duration of the audio in seconds.

### Response Example (Running)
```json
{
  "job_id": "abc123",
  "status": "running",
  "progress": {
    "current_ms": 699000,
    "total_ms": 1099000,
    "percent": 63
  }
}
```

### Response Example (Success)
```json
{
  "job_id": "abc123",
  "status": "success",
  "result": {
    "text": "...",
    "language": "es",
    "duration_seconds": 1099
  }
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.