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 apiKeydirectly 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()),
);

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 AbortSignalvia 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. 60+ languages supported with automatic detection. Request and response shape follows the public transcription-API conventions, so 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"}

Accepts diarize=true to label segments with speaker IDs (SPEAKER_00 etc.). See Speaker diarization for pricing and quotas.

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

Speaker diarization adds who said what on top of a normal transcript. Pass diarize=true when you submit an async job and every segment in the response comes back labelled with speaker: "SPEAKER_00", "SPEAKER_01", etc., plus a top-level diarization block with the detected speaker count.

Async only

Diarization is available on the async endpoints (POST /v1/transcriptions for YouTube, POST /v1/transcriptions/upload for files). The sync endpoint (POST /v1/audio/transcriptions) does not accept the flag — diar adds ~30s of processing on a one-minute clip, which doesn't fit a request-response timeout.

Speaker count hints

If you know how many people are on the recording, say so. On clean audio auto-detection works well, but on far-field or heavily compressed recordings the clusterer can invent an extra speaker out of background voices or artifacts. Three optional fields:

• num_speakers — lock clustering to exactly N. Best when the count is known: a support call is 2, a panel interview with three interviewers is 4.
• min_speakers / max_speakers — bound auto-detection when you only know a range. Ignored if num_speakers is set.

Request

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

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

Response

Same poll endpoint as a regular async job (GET /v1/transcriptions/{id}). Two additions when the job ran with diarize=true:

1. Each entry in result.segments[] carries a speaker field ("SPEAKER_00", "SPEAKER_01", …) and start / end in seconds.
2. A new result.diarization block:{ speaker_count, spans }.

{
  "job_id": "abc123...",
  "status": "success",
  "result": {
    "text": "Hola, ¿cómo estás? Bien, gracias.",
    "language": "es",
    "duration_seconds": 6.4,
    "segments": [
      {
        "start": 0.0,
        "end": 1.8,
        "text": "Hola, ¿cómo estás?",
        "speaker": "SPEAKER_00"
      },
      {
        "start": 2.1,
        "end": 4.3,
        "text": "Bien, gracias.",
        "speaker": "SPEAKER_01"
      }
    ],
    "diarization": {
      "speaker_count": 2,
      "spans": 4
    }
  }
}

Pricing & quotas

Diarized jobs debit 1.5× the audio duration from your balance (a 60-second clip with diarize=true consumes 90 seconds). On top of that, each plan has a monthly diarization quotathat's separate from the balance — when you hit it, the endpoint returns 402 until the quota resets on the 1st of the next month.

Check your remaining quota live at GET /v1/usage/diarization(returns plan, used_seconds, limit_seconds, resets_at).

Latency

Diarization runs after the whisper transcription and adds compute proportional to the audio length. On the cluster today: ~0.5× real-timefor the diar pass on top of whisper's 96×. Practical wall-clock guidance:

Accuracy notes

• Best on clean recordings (single-channel mic, low background noise) with 2-4 speakers. Beyond 4 speakers, expect over-clustering and label drift.
• Speaker labels (SPEAKER_00 etc.) are per-job: the same person across two separate requests will get different labels. Identity tracking across jobs is on the roadmap.
• Audio with heavy overlap (panel debates, sportscasts) sees accuracy drop sharply. Use the underlying segments + words to reconcile manually if your domain requires it.
• Languages: the diarizer is language-agnostic (it works on speaker timbre, not phonemes), so it pairs with any of the 60+ STT languages.

Combine with webhooks

Recommended for any clip over a couple of minutes: pass webhook_url alongside diarize=true so the result POSTs to your endpoint when it lands, instead of polling. See Webhooks & n8n for the payload shape.

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

   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.

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. Mix Transcribe and Synthesize freely — no per-product cap to juggle.