Raw schema
{
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "One chat bubble. Emoji show but are not spoken, so carry no meaning in them alone."
},
"from": {
"type": "string",
"enum": [
"left",
"right"
],
"description": "`right` is the phone's owner (the viewer), `left` is who they text. One speaker, one side."
}
},
"required": [
"text",
"from"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 200,
"description": "The conversation, in order, one entry per chat bubble. This is the script, and you write it."
},
"contact_name": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "The name at the top of the phone screen: who the owner is texting ('Mom', 'Jake ❤️')."
},
"template": {
"type": "string",
"enum": [
"imessage",
"imessage-dark",
"iphone",
"iphone-dark",
"whatsapp",
"whatsapp-dark",
"instagram",
"instagram-dark"
],
"description": "The chat app skin. Defaults to `imessage`."
},
"voice_provider_left": {
"type": "string",
"enum": [
"openai",
"elevenlabs"
],
"description": "Who reads the LEFT side. `elevenlabs` is the web app's default, `openai` is cheaper and covers every language with the same eight voices. Defaults to `openai`. IT CHANGES THE PRICE: ElevenLabs costs about four times openai per character, so call `estimate_only` again after changing it."
},
"voice_left": {
"type": "string",
"maxLength": 64,
"description": "The voice for the LEFT side. The voice id, in the provider named by `voice_provider_*` (omit for its first voice). openai: alloy, ash, ballad, coral, echo, sage, shimmer, verse (retired `onyx`, `nova`, `fable` still work). elevenlabs: an id from `list_voices` with `provider: 'elevenlabs'` (`usable_for: 'audio', limit: 100`; read `has_more`). Any other id is refused uncharged. Cloned and custom ElevenLabs voices ARE accepted here and on `generate_image_story`; `generate_audio` cannot."
},
"voice_speed_left": {
"type": "number",
"enum": [
1,
1.15,
1.25
],
"description": "The LEFT side's reading speed. 1 normal (default), 1.15 fast, 1.25 very fast. Faster makes the video shorter and costs nothing extra (the price is per character)."
},
"voice_provider_right": {
"type": "string",
"enum": [
"openai",
"elevenlabs"
],
"description": "Who reads the RIGHT side: same choices and price rule as `voice_provider_left`."
},
"voice_right": {
"type": "string",
"maxLength": 64,
"description": "The voice for the RIGHT side: same rules as `voice_left`."
},
"voice_speed_right": {
"$ref": "#/properties/voice_speed_left",
"description": "The RIGHT side's reading speed: as `voice_speed_left`."
},
"language": {
"type": "string",
"maxLength": 40,
"description": "The language the conversation is written in, by name ('English', 'German'); default English. Write `messages` in it too: this labels the script, it does not translate it."
},
"background": {
"type": "string",
"enum": [
"random",
"greenscreen"
],
"description": "`random` (a gameplay clip, the usual choice) or `greenscreen` (plain, to key out later). Default `random`."
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9"
],
"description": "Defaults to `9:16`, the vertical shape every short-form platform wants."
},
"notification_sounds": {
"type": "boolean",
"description": "Play a message tone as each bubble arrives. Defaults to true."
},
"estimate_only": {
"type": "boolean",
"description": "Price only; creates nothing."
},
"idempotency_key": {
"type": "string",
"description": "Retry key (IDEMPOTENCY)."
}
},
"required": [
"messages",
"contact_name"
],
"additionalProperties": false
}