Documentation menu
POST/v1/voice/clips
Access and price
| Auth | An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Needs a full key; a browser (maps) key is refused. |
|---|---|
| Price | 1 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. |
| Premium | When 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
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
| Field | Type | Required | Description |
|---|---|---|---|
| format | string | yes | Container: opus (Ogg Opus 48 kHz, for Android) or m4a
(MPEG-4 AAC 44.1 kHz, for iOS, which cannot play Ogg Opus). |
| gender | string | no | female 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. |
| locale | string | no | BCP 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). |
| providers | string[] | no | Provider 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. |
| utterances | UtteranceRequest[] | yes | The sentences to speak, at most [MAX_UTTERANCES]. |
| voice | string | no | Registry 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
{
"format": "string",
"utterances": [
{
"text": "string"
}
]
}Responses
pending for clips still being synthesised| Field | Type | Required | Description |
|---|---|---|---|
| clips | ClipAnswer[] | yes | One entry per requested utterance, in request order. |
| voice | VoiceDescriptor | yes | The 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
{
"clips": [
{
"cached": false,
"hash": "string",
"text": "string"
}
],
"voice": {
"gender": "female",
"id": "string",
"model": "string",
"provider": "string"
}
}unknown_voice: no such voice, locale or genderapplication/problem+json · Problem
unauthorized); the body carries signup, docs and a one-call hint for a free keyapplication/problem+json · Problem
X-PAYMENT). Not problem+jsonapplication/json · X402PaymentRequired
scope-insufficient), a request from an origin the key does not allow (origin-not-allowed), or an account restriction (forbidden)application/problem+json · Problem
voice_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 serviceapplication/problem+json · Problem
text/plain
not_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
rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)application/problem+json · Problem
application/problem+json · Problem
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