Orchard API

Three steps to your first request — same flow whether you start with Transcribe or Synthesize. One API key, one balance.

1. Sign up at /signup.
2. Activate a plan at /billing — Free includes 500 min/month (covers both products), paid plans start at $1.
3. Generate an API key at /keys. The raw key (ork_…) is shown once — copy it.

Then, transcribe an MP3 — or jump to Synthesize for text-to-speech:

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

Skip the raw HTTP plumbing. The official @orchardrun/sdk package wraps every endpoint with typed methods, automatic retries on 5xx, and typed errors you can instanceof instead of string-matching. Universal — Node 18+, Bun, Deno, browsers, Cloudflare Workers, Vercel Edge.

Install

pnpm add @orchardrun/sdk

Quickstart

Set ORCHARD_API_KEY in your env (or pass apiKey directly to the constructor) and you're three lines from a transcript.

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.",
});

Vercel AI SDK provider

Orchard ships a first-class provider for the Vercel AI SDK. If you already use transcribe() or generateSpeech() from ai, switching to Orchard is a one-line provider swap.

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" } },
});

Typed errors

Every non-2xx maps to an OrchardError subclass. Catch the specific one for retry / upgrade-CTA logic — no string matching on error.message needed.

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;
}

Cancellation

Every method accepts an AbortSignal via the optional second argument. Useful when you're wiring up a "cancel transcription" button on a long upload.

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

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

Full API surface, changelog and contributing guide on npm and GitHub.

Every endpoint except POST /v1/auth/* and /v1/billing/webhook requires authentication. Two interchangeable methods:

• API key (recommended for programmatic access): Authorization: Bearer ork_... or X-API-Key: ork_....
• JWT (used by the web dashboard, obtainable via POST /v1/auth/login): Authorization: Bearer eyJhbGciOi....

Keys are SHA-256 hashed at rest and revocable instantly from /keys. The raw token is shown only on creation — there is no recovery flow.

POST /v1/audio/transcriptions accepts a standard multipart upload and blocks until the cluster returns a transcript. Request and response shape follows the public transcription-API conventions — any SDK that speaks that format plugs in by pointing its base URL at Orchard.

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

Multipart fields

Blocking: the request waits for the cluster to finish (timeout 600s). For long audio prefer the async endpoints below.

For long audio (or YouTube URLs) submit a job, get back a job_id, and poll until status issuccess. Concurrency is capped per plan (see Limits); excess requests queue rather than fail.

POST /v1/transcriptions · YouTube URL

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"}'

# → 202 Accepted
# {"job_id": "abc123...", "status": "queued"}

POST /v1/transcriptions/upload · file

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

# → 202 Accepted
# {"job_id": "...", "status": "queued"}

GET /v1/transcriptions/{id} · poll

Returns the job's status plus a live progress snapshot while running, and the full result payload once succeeded.

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

# {"job_id":"abc123","status":"running",
#  "progress":{"current_ms":699000,"total_ms":1099000,"percent":63}}

# Once done:
# {"job_id":"abc123","status":"success",
#  "result":{"text":"...","language":"es","duration_seconds":1099, ...}}

GET /v1/transcriptions/{id}/download · formatted

Same job, rendered in the format you ask for. Returns the file with a Content-Disposition: attachment header.

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

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

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

Pass webhook_url when you create a job and Orchard POSTs the result to that URL when the job finishes. No polling needed — perfect for n8n / Zapier / Make.

Sending a job with a webhook

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"
  }'

Payload Orchard POSTs to your URL

Same shape as GET /v1/transcriptions/{id}:

{
  "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"
}

Headers we send

Retry & idempotency

• 3 attempts total with exponential backoff: 1s · 5s · 25s.
• 2xx = success. We stop retrying.
• 4xx = permanent failure. We do not retry — fix your endpoint.
• 5xx or network errors = retried up to 3 attempts.
• Use X-Orchard-Job-Id to dedupe — same id may arrive more than once.

Ready-made n8n workflows

Importable JSON — open n8n → Workflows → Import from File. Replace the placeholder API key and destination IDs before running.

• orchard-youtube-to-notion.json — Webhook trigger → POST YouTube URL → wait for result → save to a Notion DB.
• orchard-upload-to-airtable.json — Webhook trigger receiving an audio file → POST to /upload → wait → save row in Airtable.

Both templates use n8n's Wait node in webhook mode. The {{$execution.resumeUrl}} expression resolves to a unique URL per run, so each transcription resumes the right execution.

Orchard Dictate for VS Code / Cursor — hit a hotkey, speak, get the transcript inserted at your cursor. Built for dictating prompts to AI coding agents (Cursor, Copilot, Claude) without breaking flow.

Requirements

• sox installed (provides the rec binary the extension uses to capture mic audio).
  • macOS: brew install sox
  • Debian / Ubuntu: sudo apt-get install sox
• An Orchard API key (create one at /keys).
• Microphone permission for VS Code / Cursor in your OS privacy settings.

Install

1. Install from the Visual Studio Marketplace — click Install, or in VS Code / Cursor open the Extensions sidebar and search Orchard Dictate. From the command line:
   bash

   copy

   code --install-extension Orchardrun.orchard-dictate

2. Run the command Orchard: Set API Key (or click the ⚙️ next to the 🎤 Dictate status bar item) and paste your ork_… key. That's it — the extension ships pointed at https://api.orchardrun.com.

Usage

• Cmd+Shift+8 (macOS) / Ctrl+Shift+8 (Win/Linux) — start recording.
• Same shortcut again — stop, transcribe, insert at cursor.

Settings

Troubleshooting

• Nothing happens on the hotkey: sox is probably not installed. The extension probes /opt/homebrew/bin/rec, /usr/local/bin/rec, and /usr/bin/rec before falling back to PATH, so install location shouldn't matter as long as one of those exists.
• Recording runs but transcript is empty: mic permission missing for your editor in OS settings.

POST /v1/tts/generate takes text + a voice id and returns a WAV. Synchronous — request blocks for ~1-2s on common short texts (the response body IS the audio file). Served by the same private inference cluster that handles transcription.

Request

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

Form fields

Response

• 200 OK with Content-Type: audio/wav — body is the raw 22.05 kHz / 16-bit mono WAV. Stream-friendly to disk or to a browser <audio> tag.
• 404 if voice_id is unknown.
• 402 if your balance is exhausted (see Limits & pricing).
• 429 if you exceed the concurrent-request limit for your plan.

Billing

Each request debits the user's balance by the duration of the generated audio. A 30-second synthesized clip costs 30 seconds from the same balance Transcribe uses. The audio is generated at roughly 1000 characters / minute of speech, so a 500-char input consumes ~30 seconds.

Cross-language synthesis

If your input text is in one language but you pick a voice in another, Orchard auto-translates before synthesis:

# 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

Auto-translation falls back to the original text if the translation provider is unreachable — same-language synthesis always works.

Generic voices available out of the box. Hit GET /v1/tts/voices/generic at runtime for the canonical list (it's public — no auth required, useful for populating a voice picker in your UI).

Picking the right voice for your audience

The country code in the voice id (es_ES vs es_MX) drives accent. A LATAM audience listening to es_ES-davefx will hear a Castilian accent (the θ sound on c/z); for neutral LATAM use the es_MX voices.

Programmatic listing

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

Returns an array of objects with voice_id, language (ISO 639-1), locale (e.g. es_MX), flag, gender, and description. Use this in production rather than hard-coding — the catalog grows as new voices ship.

Upload a 6-60 s reference recording, give it a name, and Orchard regenerates any text in that speaker's voice. Two-step flow: create persists the voice (one-time embed compute); synthesize generates audio from cached state on every subsequent call.

POST /v1/voices · create from audio

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"

Form fields

Response

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

Returns 402 when you've hit your plan's cloned-voice quota — delete an existing voice (frees a slot) or upgrade. See the per-plan limits in Limits & pricing.

GET /v1/voices · list + quota

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

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

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

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

Form fields

Returns audio/wav bytes (16-bit PCM, 24 kHz mono). Debits from your shared per-second balance. Sampling hyperparameters are tuned server-side and not exposed — they're calibrated per engine for max fidelity.

PATCH /v1/voices/{id} · rename

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

Embedding stays intact — only the label changes. Avoids the delete-and-recreate workflow that would force a re-record.

DELETE /v1/voices/{id}

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

Returns 204. Frees a slot in your quota immediately. The embedding bytes are deleted — recreating the same voice requires a fresh reference recording.

Privacy notes

For Premium ES voices, the source WAV is persisted alongside the transcribed reference text — both are required for every synth on that tier. For Multilingual voices, only a compact conditioning embedding (~130 KB) is stored; the source WAV is discarded after the one-time embed compute. Either way: DELETE removes all artefacts permanently.

Five formats supported on the download endpoint. The sync API uses response_format and supports json, verbose_json, and text.

We accept any audio container ffmpeg can decode (mp3, m4a, ogg, opus, flac, wav, mp4, webm). The format you pick changes upload latency, not transcription quality — every request runs on the same model.

Send Opus instead of WAV

WAV is uncompressed PCM. A 15-minute speech file is ~27 MB as WAV and only ~2 MB as Opus 32kbps. The transcription is identical (Opus at speech bitrates is perceptually lossless for our STT engine); the upload is ~8x faster and you stop bumping into upload limits on long audios.

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

Already using Opus? WhatsApp voicenotes (.ogg) and browser MediaRecorder defaults are already Opus — pass them through directly.

Use sync vs async deliberately

• Sync (POST /v1/audio/transcriptions) blocks. Best for short clips (≤2 min) where waiting on the response is fine.
• Async + webhook (POST /v1/transcriptions/upload with webhook_url) frees the caller immediately and pushes the result when ready. Best for n8n / Zapier and audio over a couple of minutes.
• Avoid polling when you can use a webhook — polling every 1-2s adds the same cumulative wait but burns request quota.

Hint header

Sync responses include X-Orchard-Hint when we notice an inefficient upload (e.g. WAV > 5 MB). Surface it in your client logs the first time it appears and you'll catch slow paths before they show up as user-visible latency.

All error responses share the same shape: { "detail": "..." }.

One unified balance per plan, metered in seconds of audio. A 30-second transcription consumes 30 seconds; a 30-second synthesized clip consumes 30 seconds; a 30-second voice clone consumes 30 seconds. Mix the three products freely — no per-product cap to juggle.