Gemini 2.5 Pro Text to Speech

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /jobs/createTask

Full URL: https://ai.modelfold.online/v1/jobs/createTask

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

Text-to-speech with Gemini 2.5 Pro.

Output: WAV (16-bit PCM, 24 kHz, mono).

Query Task Status

After submitting a task, use the unified query endpoint to check progress and retrieve results:

Get Task Details — Learn how to query task status and retrieve generation results

TIP

For production use, we recommend using the callBackUrl parameter to receive automatic notifications when generation completes, rather than polling the status endpoint.

Market Overview — Explore all available models
File Upload API — Learn how to upload and manage files
Common API — Check credits and account usage

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
`model`	`string`	Yes	Model to be used Default：`"google/gemini-2-5-pro-tts"`。 Allowed values：`google/gemini-2-5-pro-tts`。示例：`google/gemini-2-5-pro-tts`。
`callBackUrl`	`string`	No	Callback URL for the result
`input`	`object`	Yes	Input parameters for the generation task
`input.temperature`	`number`	No	Sampling temperature, e.g., 1 Default：`1`。示例：`1`。
`input.scene`	`string`	No	Scene description, e.g., "A quiet, warm room with a fireplace crackling softly." Default：`""`。示例：``。
`input.sample_context`	`string`	No	Sample context/overall tone, e.g., "Audiobook style narration. Tone is gentle and inviting." Default：`""`。示例：``。
`input.speakers`	`array<object>`	Yes	List of speaker configurations
`input.speakers[].speaker_id`	`string`	Yes	Speaker identifier, e.g., "Speaker 1" or "Speaker 2"; must be in the "Speaker N" format
`input.speakers[].voice_name`	`string`	Yes	Voice name, e.g., "Zephyr", "Fenrir", "Puck" Allowed values：`Achernar` / `Achird` / `Algenib` / `Algieba` / `Alnilam` / `Aoede` / `Autonoe` / `Callirrhoe` / `Charon` / `Despina` / `Enceladus` / `Erinome` / `Fenrir` / `Gacrux` / `Iapetus` / `Kore` / `Laomedeia` / `Leda` / `Orus` / `Puck` / `Pulcherrima` / `Rasalgethi` / `Sadachbia` / `Sadaltager` / `Schedar` / `Sulafat` / `Umbriel` / `Vindemiatrix` / `Zephyr` / `Zubenelgenubi`。示例：`Achernar`。
`input.speakers[].audio_profile`	`string`	No	Audio profile description, e.g., "A warm and soothing narrator" or "A stern and weary gatekeeper"
`input.speakers[].accent`	`string`	Yes	Accent, e.g., "British (RP)" or "American (Gen)" Allowed values：`Neutral` / `American (Gen)` / `American (Valley)` / `American (South)` / `British (RP)` / `British (Brixton)` / `Transatlantic` / `Australian`。示例：`Neutral`。
`input.speakers[].style`	`string`	No	Emotional style, e.g., "Whisper" or "Deadpan" Allowed values：`Vocal Smile` / `Newscaster` / `Whisper` / `Empathetic` / `Promo/Hype` / `Deadpan`。示例：`Vocal Smile`。
`input.speakers[].pace`	`string`	No	Pace, e.g., "Staccato" or "Natural" Allowed values：`Natural` / `Rapid Fire` / `The Drift` / `Staccato`。示例：`Natural`。
`input.dialogue_turns`	`array<object>`	Yes	List of dialogue turns, output in sequential order
`input.dialogue_turns[].speaker_id`	`string`	Yes	Corresponding speaker identifier, e.g., "Speaker 1"
`input.dialogue_turns[].text`	`string`	Yes	The text spoken by the speaker, which may contain tone tags, e.g., "Once upon a time, in a quiet valley hidden away..."

Request Example

bash

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "google/gemini-2-5-pro-tts",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "temperature": 1,
    "scene": "A dark, crumbling dungeon...",
    "sample_context": "Fantasy RPG style...",
    "speakers": [
      {
        "speaker_id": "Speaker 1",
        "voice_name": "Fenrir",
        "audio_profile": "A stern and weary gatekeeper",
        "accent": "British (RP)",
        "style": "Deadpan",
        "pace": "Natural"
      },
      {
        "speaker_id": "Speaker 2",
        "voice_name": "Puck",
        "audio_profile": "A determined and courageous traveler seeking answers.",
        "accent": "American (Gen)",
        "style": "Empathetic",
        "pace": "Staccato"
      }
    ],
    "dialogue_turns": [
      {
        "speaker_id": "Speaker 1",
        "text": "[shouting] Halt, traveler! The northern pass is sealed by order of the council."
      },
      {
        "speaker_id": "Speaker 2",
        "text": "[determination] I carry a message for the elder. Step aside, or I will force my way through."
      },
      {
        "speaker_id": "Speaker 1",
        "text": "[caution] No one passes. [pensive] The elder is... he'\''s no longer receiving visitors."
      },
      {
        "speaker_id": "Speaker 2",
        "text": "It'\''s too late. [whispers] The shadow... it reached him first. [urgency] You need to leave. [shouting] Now."
      }
    ]
  }
}'

json

{
  "model": "google/gemini-2-5-pro-tts",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "temperature": 1,
    "scene": "A dark, crumbling dungeon...",
    "sample_context": "Fantasy RPG style...",
    "speakers": [
      {
        "speaker_id": "Speaker 1",
        "voice_name": "Fenrir",
        "audio_profile": "A stern and weary gatekeeper",
        "accent": "British (RP)",
        "style": "Deadpan",
        "pace": "Natural"
      },
      {
        "speaker_id": "Speaker 2",
        "voice_name": "Puck",
        "audio_profile": "A determined and courageous traveler seeking answers.",
        "accent": "American (Gen)",
        "style": "Empathetic",
        "pace": "Staccato"
      }
    ],
    "dialogue_turns": [
      {
        "speaker_id": "Speaker 1",
        "text": "[shouting] Halt, traveler! The northern pass is sealed by order of the council."
      },
      {
        "speaker_id": "Speaker 2",
        "text": "[determination] I carry a message for the elder. Step aside, or I will force my way through."
      },
      {
        "speaker_id": "Speaker 1",
        "text": "[caution] No one passes. [pensive] The elder is... he's no longer receiving visitors."
      },
      {
        "speaker_id": "Speaker 2",
        "text": "It's too late. [whispers] The shadow... it reached him first. [urgency] You need to leave. [shouting] Now."
      }
    ]
  }
}

Response

200 — Request successful

参数	类型	必填	说明
`code`	`integer`	否	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200` / `401` / `402` / `404` / `422` / `429` / `455` / `500` / `501` / `505`。示例：`200`。
`msg`	`string`	否	Response message, error description when failed 示例：`success`。
`data`	`object`	是	—
`data.taskId`	`string`	否	Task ID, can be used with Get Task Details endpoint to query task status

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_1765185282276"
  }
}

500 — Server error.

参数	类型	必填	说明
`code`	`integer`	是	Response status code - 200: Success - Request has been processed successfully - 401: Unauthorized - Authentication credentials are missing or invalid - 402: Insufficient Credits - Account does not have enough credits to perform the operation - 404: Not Found - The requested resource or endpoint does not exist - 408: Timeout - No result has been returned for over 10 minutes. - 422: Validation Error - The request parameters failed validation checks - 429: Rate Limited - Request limit has been exceeded for this resource - 455: Service Unavailable - System is currently undergoing maintenance - 500: Server Error - An unexpected error occurred while processing the request - 501: Generation Failed - Content generation task failed - 505: Feature Disabled - The requested feature is currently disabled
`msg`	`string`	是	Response message, error description when failed
`data`	`object`	是	—

json

{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}

Callback

musicTaskCompleted

Callback URL: {request.body#/callBackUrl} (the callBackUrl in the request body).

The system sends this callback when the audio task succeeds or fails.

Callback body parameters

参数	类型	必填	说明
`code`	`integer`	是	Unified callback code: 200 for success, 501 for failure. Allowed values：`200` / `501`。示例：`200`。
`msg`	`string`	是	Unified callback message. Allowed values：`Playground task completed successfully.` / `Playground task failed.`。示例：`Playground task completed successfully.`。
`data`	`object`	是	—
`data.taskId`	`string`	是	The unique task identifier.
`data.model`	`string`	是	The model used for the task. Allowed values：`google/gemini-2-5-pro-tts`。示例：`google/gemini-2-5-pro-tts`。
`data.state`	`string`	是	Terminal task state. Allowed values：`success` / `fail`。示例：`success`。
`data.param`	`string`	是	JSON string containing the submitted task parameters.
`data.resultJson`	`string`	否	JSON string containing resultUrls and resultObject when successful. Present only when state is success.
`data.failCode`	`string`	否	Failure code, a numeric string such as "400" or "500". Present only when state is fail.
`data.failMsg`	`string`	否	Failure reason. Present only when state is fail.
`data.costTime`	`integer`	否	Processing time in seconds. Present on both success and failure callbacks.
`data.completeTime`	`integer`	否	Task completion timestamp.
`data.createTime`	`integer`	否	Task creation timestamp.
`data.updateTime`	`integer`	否	Use completeTime as the completion time; updateTime may equal createTime.
`data.creditsConsumed`	`number`	否	Credits consumed by the task; 0 for failed tasks.

Task completed successfully

json

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "task_example_music_webhook_001",
    "model": "google/gemini-2-5-pro-tts",
    "state": "success",
    "param": "{\"input\":\"{\\\"temperature\\\":1,\\\"scene\\\":\\\"A dark, crumbling dungeon...\\\",\\\"sample_context\\\":\\\"Fantasy RPG style...\\\",\\\"speakers\\\":[{\\\"speaker_id\\\":\\\"Speaker 1\\\",\\\"voice_name\\\":\\\"Fenrir\\\",\\\"audio_profile\\\":\\\"A stern and weary gatekeeper\\\",\\\"accent\\\":\\\"British (RP)\\\",\\\"style\\\":\\\"Deadpan\\\",\\\"pace\\\":\\\"Natural\\\"}],\\\"dialogue_turns\\\":[{\\\"speaker_id\\\":\\\"Speaker 1\\\",\\\"text\\\":\\\"[shouting] Halt, traveler! The northern pass is sealed by order of the council.\\\"}]}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"google/gemini-2-5-pro-tts\"}",
    "resultJson": "{\"resultUrls\":[\"https://example.com/generated-audio.wav\"],\"resultObject\":null}",
    "costTime": 12,
    "completeTime": 1234567890,
    "createTime": 1234560000,
    "updateTime": 1234567890,
    "creditsConsumed": 1.23
  }
}

Task failed

json

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "task_example_music_webhook_001",
    "model": "google/gemini-2-5-pro-tts",
    "state": "fail",
    "param": "{\"input\":\"{\\\"temperature\\\":1,\\\"scene\\\":\\\"A dark, crumbling dungeon...\\\",\\\"sample_context\\\":\\\"Fantasy RPG style...\\\",\\\"speakers\\\":[{\\\"speaker_id\\\":\\\"Speaker 1\\\",\\\"voice_name\\\":\\\"Fenrir\\\",\\\"audio_profile\\\":\\\"A stern and weary gatekeeper\\\",\\\"accent\\\":\\\"British (RP)\\\",\\\"style\\\":\\\"Deadpan\\\",\\\"pace\\\":\\\"Natural\\\"}],\\\"dialogue_turns\\\":[{\\\"speaker_id\\\":\\\"Speaker 1\\\",\\\"text\\\":\\\"[shouting] Halt, traveler! The northern pass is sealed by order of the council.\\\"}]}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"google/gemini-2-5-pro-tts\"}",
    "failCode": "400",
    "failMsg": "<error detail>",
    "costTime": 12,
    "creditsConsumed": 0
  }
}

Gemini 2.5 Pro Text to Speech ​

Endpoint ​

Query Task Status ​

Related Resources ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request successful ​

500 — Server error. ​

Callback ​

musicTaskCompleted ​

Gemini 2.5 Pro Text to Speech

Endpoint

Query Task Status

Related Resources

Request Parameters

Body (application/json)

Request Example

Response

200 — Request successful

500 — Server error.

Callback

musicTaskCompleted