API & MCP

Create a transcription

Start an async job from a link, a podcast feed, or a file you have already uploaded.

In short

POST /api/v1/transcriptions with exactly one source: a remote url (audio or video file, podcast RSS or Apple link, or a social link), a media_ref from a direct upload, or a public blob_url. The call returns 202 with a job id and status queued; poll it or wait for a webhook.

The request

Pass exactly one source. A remote url covers an audio or video file, a podcast RSS or Apple link, or a social link. A media_ref comes from a direct upload, and a public blob_url covers media you already host somewhere reachable.

Send an Idempotency-Key header and retries become safe: repeating the same key returns the original job rather than starting a second one.

Start a job

curl -X POST https://pepys.co/api/v1/transcriptions \
  -H "Authorization: Bearer pk_live_…" \
  -H "Idempotency-Key: my-unique-id" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/episode.mp3",
    "diarize": true,
    "summary": true,
    "language": "en"
  }'

# → 202 { "id": "…", "status": "queued", "url": "/api/v1/transcriptions/…" }

Options

language takes an ISO code; omit it to auto-detect. diarize detects speakers and is billed at 3× on long-form. summary and chapters add the AI extras. translate_to takes an ISO code and also returns a translation. quality selects fast or accurate.

When a job is already done

A cached source, or one that arrives with provider captions already attached, returns 200 with status: "done" immediately instead of queueing. Treat that as success and read the transcript straight away rather than polling.

What comes next

The response id is what you poll with Get a transcription, or what a webhook tells you about when the job finishes. Whole podcast feeds can be started in one call with the podcasts endpoints.

Create a transcription – questions, answered

Which endpoint starts a transcription?

POST /api/v1/transcriptions. It accepts exactly one source per request and returns 202 with the job id and a queued status.

What sources can I pass?

A remote url (audio or video file, podcast RSS or Apple link, or a social link), a media_ref from a direct upload, or a public blob_url.

How do I make retries safe?

Send an Idempotency-Key header. Repeating the same key returns the original job instead of creating a second transcription.

What does diarize cost?

Diarization is billed at 3× on long-form jobs. It is one of the options on the create call, alongside summary, chapters, and translate_to.

Why did my request return 200 instead of 202?

The source was cached or already had provider captions, so the job was complete immediately. The response carries status: "done" and the transcript.

Try it on your own audio

Create a free account and transcribe a recording – 60 minutes are included, no card required. Still stuck? Email contact@pepys.co or see the support page.