Skip to content
Numes

API reference · Create transcription

Media

Create transcription

Transcribe an audio file to text, uploaded as multipart form data or as base64 JSON.

POSThttps://api.numes.ai/api/v1/audio/transcriptions

Send exactly one audio file, either as a multipart file part or as JSON file/audio objects with base64 data and a format. response_format is json (default) or verbose_json; both return text and usage only, without word or segment timestamps. prompt is accepted but has no effect. Guide: Speech and transcription.

The same request as multipart form data:

Shell
curl https://api.numes.ai/api/v1/audio/transcriptions \  -H "Authorization: Bearer $NUMES_API_KEY" \  -F model=author/transcription-model \  -F file=@meeting.wav \  -F response_format=json

Authorization

AuthorizationheaderRequired

Bearer inference key. Charges settle in the key's billing currency. Authorization: Bearer $NUMES_API_KEY

Headers

X-Request-Idstring

Correlation ID, not an idempotency key. Inference request IDs recorded with a generation are unique per account. A traffic-admitted request reusing a recorded ID returns 400 invalid_request. Traffic admission rejection takes precedence over this conflict, including for reused IDs; it performs no generation lookup and writes no generation, result or attempt. Rate-limit rejection returns 429 rate_limited with Retry-After; an inference limiter outage retains 500 server.

Length1–128

Request body

multipart/form-dataapplication/json

The contract declares a 25 MiB body limit. The size the service enforces is listed in Limits.

multipart/form-data

filefileRequired
modelstringRequired
Length≤ 393
Pattern^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$
languagestring
promptstring
response_formatenum<string>
Default"json"
One ofjsonverbose_json
temperaturenumber
Range0–1
timestamp_granularitiesarray<enum<string>>
One ofwordsegment
Items≤ 2

application/json

modelstringRequired
Length≤ 393
Pattern^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$
fileobject
Show2 child attributes
datastringRequired
Encodingbase64
formatenum<string>Required
One ofwavmp3flacm4aoggwebmaacaiffpcm16pcm24
audioobject
Show2 child attributes
datastringRequired
Encodingbase64
formatenum<string>Required
One ofwavmp3flacm4aoggwebmaacaiffpcm16pcm24
languagestring
promptstring
Length≤ 4,096
response_formatenum<string>
Default"json"
One ofjsonverbose_json
temperaturenumber
Range0–1
timestamp_granularitiesarray<enum<string>>
One ofwordsegment
Items≤ 2

Responses

200Transcriptionapplication/json

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

BodyTranscriptionResponseapplication/json

textstringRequired
usageobjectRequired
Show5 child attributes
typestringRequired
Value"duration"
secondsnumberRequired
Range≥ 0
input_audio_secondsnumberRequired
Range≥ 0
output_tokensintegerRequired
Range≥ 0
costnumberRequired
Range≥ 0
503No eligible provider can serve the request. Unknown, unpublished, currency-mismatched and unauthorized shared model IDs receive the same bounded response (`error.code` 503, `error.metadata.error_type` "provider_unavailable", message "no provider is available"). Inference and encrypted resolution do not classify model existence after routing fails. Earlier validation and authorization errors remain unchanged. An interrupted server execution while the original HTTP caller remains connected also uses 503 provider_unavailable with the fixed message "service temporarily unavailable". Once streaming has started, the error is in-band and the HTTP status remains 200. If an otherwise eligible USD-indexed Bitcoin offer is blocked by an unavailable market reference, or its reference expires before dispatch, the response instead uses 503 with error_type "bitcoin_reference_price_unavailable" and message "Bitcoin pricing is unavailable. Try again shortly."application/json

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

BodyErrorResponseapplication/json

errorobjectRequired
Show3 child attributes
codeintegerRequired
messagestringRequired
metadataobject
openrouter_metadataobject
ErrorCompatible error envelopeapplication/json

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

Retry-Afterinteger

Optional delay in seconds for retryable rate or availability errors.

Range≥ 1

BodyErrorResponseapplication/json

errorobjectRequired
Show3 child attributes
codeintegerRequired
messagestringRequired
metadataobject
openrouter_metadataobject