API

Quickstart

Sign in and create a key

Sign in or create an account and verify your email. Open the Account page’s API keys tab to create a key, then copy the secret and store it securely. It is shown only once.

Your signed-in account includes free minutes for evaluation in the web app. API-key usage is currently separate from that balance. To try the API, create a key and make the request below.

Make your first request

Set MACHINERA_API_KEY in your server environment to your saved key. Replace audio.mp3 with your file path, then run:

curl https://api.machinera.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $MACHINERA_API_KEY" \
  -F file=@audio.mp3 \
  -F model=transcribe-v1

Read the result

A successful request returns JSON with a text field:

{"text":"Your transcript appears here.","usage":{"type":"duration","seconds":12.345}}

usage is omitted when measured audio duration is unavailable. Use the transcript from the text field directly, or request word timings and quality warnings.

This deployment’s API base URL:

https://api.machinera.com/v1

Authentication and keys

Send your key in the Authorization: Bearer header on every API request.

“Shown once” means the secret cannot be displayed again: only its digest is stored. Afterwards, the list identifies it by label, key ID and masked hint. If you lose a key, create a replacement and revoke the old key by its ID; a lost key stays valid until revoked.

Keys start with ma_, followed by a mode, an underscore and 32 letters or digits. Masked examples: ma_live_0123…STUV (live); ma_test_0123…STUV (test). Keys do not cross environments: use a live-mode key for production and a test-mode key for non-production.

Manage your keys and usage on your Account page.

Production API base URL: https://api.machinera.com/v1. Use this deployment's base URL below with a key created in this environment.

Key lifecycle

You can hold multiple keys and label each for its service or use. Revoke a key by its key ID on the Account page without revoking your other keys. Revocation retains a revoked record; it does not delete the record. Keys do not expire. To rotate a key, create its replacement, move your calls to it, then revoke the old key.

Keys carry no per-key permission scopes: all keys on an account have equivalent access.403 2004: API key is forbidden.

/v1 is server-to-server: OPTIONS carries no CORS headers. Browser clients use the signed-in app path, /transcribe/api/uploads, keeping bearer keys out of browser code.

Transcribe audio: synchronous request

The call blocks until the transcript is ready and returns it in the response — the simplest path for short clips. Multipart uploads go up to 25 MiB by default; a larger body is rejected with 413 1021 (use the asynchronous mode below, or send a URL by reference). For upload advice, see the cap entries linked here and in the asynchronous section below.

curl https://api.machinera.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $MACHINERA_API_KEY" \
  -F file=@audio.mp3 \
  -F model=transcribe-v1

curl https://api.machinera.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $MACHINERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/audio.mp3", "model": "transcribe-v1"}'

Use HTTP in your application

These examples send the same multipart request. Let the client set the multipart boundary.

Python · requests

import os
import requests

with open("audio.mp3", "rb") as audio:
    response = requests.post(
        "https://api.machinera.com/v1/audio/transcriptions",
        headers={"Authorization": "Bearer " + os.environ["MACHINERA_API_KEY"]},
        files={"file": audio},
        data={"model": "transcribe-v1"},
    )
response.raise_for_status()
print(response.json()["text"])

JavaScript · built-in fetch

import { readFile } from "fs/promises";

const form = new FormData();
form.set("file", new Blob([await readFile("audio.mp3")]), "audio.mp3");
form.set("model", "transcribe-v1");
const response = await fetch("https://api.machinera.com/v1/audio/transcriptions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MACHINERA_API_KEY}` },
  body: form,
});
if (!response.ok) throw new Error(await response.text());
console.log((await response.json()).text);

Send a descriptive User-Agent. Browsers and curl already send one; a raw HTTP client should set one that names your app, e.g. my-app/1.0, so a support request can be traced back to the caller that made it.

Long audio: async jobs

Submit the audio now and get back 202 with a job id and a status of queued; then poll the job (or receive a webhook) until it finishes. Use this mode for long-form audio (full episodes) and whenever you want a durable job that survives a dropped connection. For audio above the async multipart cap below, submit it by reference (a url); a by-reference body carries no audio bytes.

For direct file uploads, follow the Upload grants and recovery contract.

curl https://api.machinera.com/v1/transcription_jobs \
  -H "Authorization: Bearer $MACHINERA_API_KEY" \
  -F file=@audio.mp3 \
  -F model=transcribe-v1

curl https://api.machinera.com/v1/transcription_jobs \
  -H "Authorization: Bearer $MACHINERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/audio.mp3", "model": "transcribe-v1", "webhook_url": "https://example.com/webhook"}'

curl https://api.machinera.com/v1/transcription_jobs/JOB_ID \
  -H "Authorization: Bearer $MACHINERA_API_KEY"

Public asynchronous submission validates the same options before accepting a job. Poll accepted jobs for terminal status. Completed jobs return full verbose JSON regardless of response_format; extract result.text for text.

Batch

POST /v1/transcription_jobs/batch submits up to 64 by-reference jobs in a JSON jobs array. Give each job its own idempotency_key; replace the example key for each new logical job.

curl https://api.machinera.com/v1/transcription_jobs/batch \
  -H "Authorization: Bearer $MACHINERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobs":[{"url":"https://example.com/audio.mp3","model":"transcribe-v1","idempotency_key":"UNIQUE_KEY_PER_JOB"}]}'

GET /v1/transcription_jobs?ids=JOB_ID,ANOTHER_JOB_ID polls up to 300 known job IDs; it is not a job listing. Replace the placeholders with IDs returned by submission.

curl --get https://api.machinera.com/v1/transcription_jobs \
  -H "Authorization: Bearer $MACHINERA_API_KEY" \
  --data-urlencode "ids=JOB_ID,ANOTHER_JOB_ID"

Both routes return ordered per-item results with each item's status, headers, and body. The call itself returns 200whenever the batch was accepted for processing, including when some items failed, so branch on each item's status_code, never on the outer status. Submissions can partially succeed; inspect each result before retrying. Honor each item's Retry-After header. For successful 200 single-job status responses, Retry-After is present for queued or processing and absent for completed or error. Batch polls also expose a top-level Retry-After when any item carries it.

The two ceilings differ deliberately and neither implies the other: the submit ceiling is sized against the request body those job descriptors add up to and the work one call fans out to, the poll ceiling against the size of the status response it returns. Chunk a larger set against whichever route you are calling.

Request options and response formats

Both modes require model=transcribe-v1. Accepted upload formats: mp3, mp4, mpeg, mpga, m4a, wav, webm, flac, ogg.

For synchronous requests, response_format=json returns {"text":"Your transcript appears here.","usage":{"type":"duration","seconds":12.345}}. usage is omitted when measured audio duration is unavailable. Pass response_format=verbose_json for the full result: language (the served language), the audio duration, usage, a warnings[] quality channel, and words (per-word timings, always returned), plus inference_seconds (total processing time spent producing this transcript. null when unavailable).timestamp_granularities[]=word is optional and is not required to receive words. Both sync and async multipart accept the bracketed form and the unbracketed field name. Use response_format=text to get the transcript back as plain text.

Inspect warnings[] in verbose results as a quality channel, even when the request succeeds. A warning is not an HTTP error.

response_format is unsupported

timestamp_granularities is unsupported

language is unsupported (English only; omit 'language' or send 'en')

Errors and retries

Errors use an error object. Required fields are message (a readable explanation), type (the error category), code (a numeric identifier), and doc_url (the code’s one-line meaning). The fields param (the offending input), retryable (retry advice), and details (additional context) are optional.

Check Content-Type before parsing: some refusals have a non-JSON body without an error object or request identifier. Record the HTTP status, a short response summary, and the request time when reporting these failures.

Limits

Audio duration is constrained by serving capacity and key tier. A terminal 429 3003 : this request exceeds the capacity available to your key; submit a shorter clip. Submitting a URL avoids uploading audio bytes in the request body, but does not bypass duration or capacity checks.

Rate limits and authentication budget

Upload initialization is limited by tier and source request rate. Its rate headers report the active allowance; Retry-After reports seconds until reset. Processing limits also apply to submitted jobs. Follow the Rate limits and backoff guidance.

Repeated authentication failures share a source budget, including callers behind the same source address. Once exhausted, even valid keys receive 429 3004 until the next UTC minute. The x-ratelimit-limit-requests, x-ratelimit-remaining-requests and x-ratelimit-reset-requests headers describe this failure budget, not a tenant request allowance. Reset is seconds remaining, not an epoch timestamp. Read the limit header for the failure allowance and honor Retry-After before retrying. Correct invalid credentials before sending more requests.

Audio URL policy

Audio URLs must use http or https and resolve only to publicly routable addresses. Private, loopback and link-local addresses are refused. Redirects are not followed; provide the final audio URL. Check public reachability and the audio format before resubmitting.

Idempotency

Use an Idempotency-Key to make asynchronous submits safe to retry. Generate a unique key per logical submit and reuse it only when retrying that exact request: while retained, the repeat replays the original job instead of re-running or double-billing it. 409 1030: the original idempotent response is no longer available. Send it on the async submit route as a header or an idempotency_key body field. Public synchronous requests have no idempotency replay guarantee; a retry may run again.

Each key is bound to a request fingerprint: the audio you submitted plus every option that shapes the transcript — model, response_format, language, and the rest. For URL input, the fingerprint uses the reference, not newly fetched bytes. Use an immutable URL or content version when deriving a key. Fields that do not change what is transcribed (webhook_url, prompt) are outside it, and omitting an option is the same request as sending its default. Reuse a key with a different fingerprint — one static key across different files, say — and the stored response answers the first request. Use a new key for a changed request. To deduplicate identical submissions rather than just network retries, derive the key from the content plus every request-affecting option — e.g. a sha256 of the file bytes with model, response_format, and language. Keys are scoped to your account, so such a content hash can never collide into another customer's result.

OpenAI-compatible clients

Optional: if you already use an OpenAI-style client, the synchronous endpoint accepts the OpenAI transcription request shape. Point the client at this deployment’s base URL and use your API key. The stock OpenAI SDK covers synchronous file transcription. Use raw HTTP for asynchronous jobs, by-URL input and batch routes.

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["MACHINERA_API_KEY"], base_url="https://api.machinera.com/v1")
with open("clip.mp3", "rb") as audio:
    transcript = client.audio.transcriptions.create(
        model="transcribe-v1",
        file=audio,
        response_format="verbose_json",
        timestamp_granularities=["word"],
    )
print(transcript.text)

Support and contact

Include the x-request-idresponse header value and the affected calls' timestamps when you report an API problem. The x-request-id shape is ^[A-Za-z0-9_.:-]{1,128}$.

Production volume and commitments

If you are evaluating production volume or need commitments, contact sales.