Skip to content
Documentation menu
docs / api / post-v1-voice-clips
Voice

POST/v1/voice/clips

Access and price

AuthAn API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Needs a full key; a browser (maps) key is refused.
Price1 call per newly synthesised clip; clips already cached are refunded. Class: standard, or premium for truck and ADR work. Published as unit_rules.default in /pricing.json.
PremiumWhen the body asks for truck routing: "costing": "truck", a top-level adr object or "hazmat": true

What it does

Synthesise (or fetch from cache) the clips a route will speak.

An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Price: 1 call per newly synthesised clip; clips already cached are refunded.

Call it

bash
curl -fsS -X POST "https://api.mapmap.ai/v1/voice/clips" \
  -H "Authorization: Bearer $MAPMAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"string","utterances":[{"text":"string"}]}'

Request body

application/json · VoiceClipsRequest

FieldTypeRequiredDescription
formatstringyesContainer: opus (Ogg Opus 48 kHz, for Android) or m4a (MPEG-4 AAC 44.1 kHz, for iOS, which cannot play Ogg Opus).
genderstringnofemale or male, alongside locale: that locale's default voice of this gender. With voice, the voice must be of this gender. Needs locale or voice.
localestringnoBCP 47 locale (en-GB, fr-FR), answered by that locale's default voice for gender, or for the locale's default gender (female) when gender is absent. With neither voice nor locale the voice is the en-GB default (en-gb-f).
providersstring[]noProvider classes this request may be answered by: elevenlabs, open (the self-hosted open-source voices) or both. A voice outside them is replaced by its fallback; ["open"] never touches ElevenLabs. Absent allows both.
utterancesUtteranceRequest[]yesThe sentences to speak, at most [MAX_UTTERANCES].
voicestringnoRegistry voice id (en-gb-f, amelia, fr-fr-m). Wins over locale; when both are sent the voice must speak that locale.

Example: A request assembled from this schema's own field examples, enums, defaults and types; not a recorded call

json
{
  "format": "string",
  "utterances": [
    {
      "text": "string"
    }
  ]
}

Responses

200Clip URLs, cache flags and durations; pending for clips still being synthesised
FieldTypeRequiredDescription
clipsClipAnswer[]yesOne entry per requested utterance, in request order.
voiceVoiceDescriptoryesThe voice the request resolved to, and the voice behind every clip here except those flagged fallback, which name their own.

Example: A response assembled from this schema's own field examples, enums, defaults and types; not a recorded call

json
{
  "clips": [
    {
      "cached": false,
      "hash": "string",
      "text": "string"
    }
  ],
  "voice": {
    "gender": "female",
    "id": "string",
    "model": "string",
    "provider": "string"
  }
}
400Invalid request, or unknown_voice: no such voice, locale or gender

application/problem+json · Problem

401Missing or invalid API key. Also: No key, or a missing, malformed, unknown, revoked or expired one (unauthorized); the body carries signup, docs and a one-call hint for a free key

application/problem+json · Problem

402Beyond the included volume with no way to pay this call: an x402 body naming how to pay (provisional key past its allowance, prepaid balance below the price, or a rejected X-PAYMENT). Not problem+json

application/json · X402PaymentRequired

403The key may not call this: a browser key outside its scope (scope-insufficient), a request from an origin the key does not allow (origin-not-allowed), or an account restriction (forbidden)

application/problem+json · Problem

409voice_not_ready: the voice exists but cannot synthesise here: no provider voice chosen yet, or an open-source voice on a gateway without the open-source voice service

application/problem+json · Problem

413The request declares a body larger than 1048576 bytes (plain text, not problem+json)

text/plain

422not_guidance_sentence: no utterance in the request is a guidance sentence the MapMap apps produce (a request with some is answered 200, with a per-clip error on the rest)

application/problem+json · Problem

429Quota or rate limit exceeded. Also: Per-key rate limit (rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)

application/problem+json · Problem

501Voice clips are not enabled (SN_VOICE_DIR unset, or neither SN_ELEVENLABS_API_KEY nor SN_TTS_URL set)

application/problem+json · Problem

504The request did not finish within the gateway's request deadline (request-timeout)

application/problem+json · Problem

Error bodies follow the shared problem model documented on API conventions.

Also under Voice

Generated from https://api.mapmap.ai/openapi.json on 2026-11-12 · operationId post_clips