POST/v1/voice/clips

API key required, sent as Authorization: Bearer snk_… or ?api_key=snk_….

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 @request.json

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.

Responses

200Clip URLs, cache flags and durations; 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.

400Invalid request, or unknown_voice: no such voice, locale or gender

401Missing or invalid API key

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

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)

429Quota or rate limit exceeded

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

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

Also under voice

GET /v1/voice/bank GET /v1/voice/clips/{clip}

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