> ## Documentation Index > Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # CosyVoice 3.5 Plus > Alibaba text-to-speech and custom voice API for custom voice clone and design workflows ## Overview CosyVoice 3.5 Plus is an Alibaba audio model for text-to-speech plus custom voice creation. Use this page when you are ready to call the API after trying the model in the APIXO playground. | Capability | Value | | -------------------- | --------------------------- | | Model ID | `cosyvoice-3-5-plus` | | Modes | `speech`, `clone`, `design` | | Built-in voices | No | | Custom voices | Yes | | Speech prompt length | 1-20000 characters | | Design prompt length | 1-500 characters | | Preview text length | 1-200 characters | | Clone audio URLs | Exactly 1 URL | ## Endpoint and authentication Base URL: ```text theme={null} https://api.apixo.ai/api/v1 ``` | Method | Endpoint | Purpose | | ------ | ------------------------------------------------ | -------------------------------------- | | `POST` | `/generateTask/cosyvoice-3-5-plus` | Submit a speech, clone, or design task | | `GET` | `/statusTask/cosyvoice-3-5-plus?taskId={taskId}` | Poll task status and retrieve results | All requests require your APIXO API key: ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` Submit requests also require: ```http theme={null} Content-Type: application/json ``` ## Copy-paste async quickstart This minimal request submits a design task and returns a `taskId`. ```bash theme={null} curl -X POST "https://api.apixo.ai/api/v1/generateTask/cosyvoice-3-5-plus" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "request_type": "async", "input": { "mode": "design", "prefix": "warm01", "prompt": "A calm and clean male narration voice for explainers.", "preview_text": "This is a voice design preview sample." } }' ``` Successful response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678" } } ``` Save the `taskId`; you need it to poll for the final result. ## Poll for result ```bash theme={null} curl -X GET "https://api.apixo.ai/api/v1/statusTask/cosyvoice-3-5-plus?taskId=task_12345678" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Processing response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "processing", "voice_id": "cosyvoice-v3.5-plus-xxxx", "voice_status": "DEPLOYING", "createTime": 1767965610929 } } ``` Success response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "success", "voice_id": "cosyvoice-v3.5-plus-xxxx", "voice_status": "OK", "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/preview.wav\"]}", "createTime": 1767965610929, "completeTime": 1767965682450, "costTime": 71521 } } ``` Failed response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "failed", "failCode": "UNDEPLOYED", "failMsg": "Voice review failed. This custom voice is unavailable (UNDEPLOYED).", "voice_id": "cosyvoice-v3.5-plus-xxxx", "voice_status": "UNDEPLOYED", "createTime": 1767965610929, "completeTime": 1767965682450 } } ``` Parse `resultJson` after `state` becomes `success`: ```javascript theme={null} const payload = JSON.parse(data.resultJson); const audioUrls = payload.resultUrls; ``` ## Request body ### Speech ```json theme={null} { "request_type": "async", "input": { "mode": "speech", "voice": "cosyvoice-v3.5-plus-xxxx", "prompt": "Welcome to APIXO.", "format": "mp3" } } ``` ### Clone ```json theme={null} { "request_type": "async", "input": { "mode": "clone", "prefix": "demo01", "audio_urls": [ "https://example.com/reference.wav" ] } } ``` ### Design ```json theme={null} { "request_type": "async", "input": { "mode": "design", "prefix": "warm01", "prompt": "A calm and clean male narration voice for explainers.", "preview_text": "This is a voice preview sample." } } ``` ## Parameters Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery. Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/docs/api-reference/webhooks). CosyVoice 3.5 Plus input parameters. Workflow type. Supported values: `speech`, `clone`, `design`. Required for `speech`. Must be a previously created `voice_id`. Required for `speech` and `design`. In `speech`, this is the synthesis text and supports 1-20000 characters. In `design`, this is the voice description and supports 1-500 characters. Required for `clone`. Must contain exactly 1 non-empty audio URL. Required for `design`. Preview text for the generated custom voice. Supports 1-200 characters. Required for `clone` and `design`. Must match `^[A-Za-z0-9]{1,10}$`. Optional output format. Passed through for `speech`. For `design`, APIXO also uses it as the preview `response_format`. If omitted in `design`, the preview defaults to `wav`. Optional sample rate. Passed through for `speech`, and also supported for clone or design preview output. Optional speaking-rate control for `speech`. Optional pitch control for `speech`. Optional volume control for `speech`. Optional instruction text for `speech`. Must not exceed 100 characters. Optional language hints. APIXO accepts either a string or string array, then keeps only the first non-empty item before sending upstream. Optional SSML toggle for `speech`. Optional word timestamp toggle for `speech`. Optional AIGC tag toggle for `speech`. Optional AIGC propagation metadata for `speech`. Optional AIGC propagation ID for `speech`. Optional speech passthrough flag supported by the current route. Optional Markdown filtering toggle for `speech`. ## Response format ### Submit task response `POST /generateTask/cosyvoice-3-5-plus` returns a task ID when the task is accepted: API status code. `200` means the task was accepted. Human-readable status message. Unique task identifier used with the status endpoint. ### Status response fields Unique task identifier. Current task state: `pending`, `processing`, `success`, or `failed`. JSON string containing audio result URLs. Present when audio output is available. Custom voice ID returned by clone or design workflows. Upstream custom voice status such as `DEPLOYING`, `OK`, or `UNDEPLOYED`. Machine-readable failure code. Present when `state` is `failed`. Human-readable failure message. Present when `state` is `failed`. Task creation timestamp in Unix milliseconds. Task completion timestamp in Unix milliseconds. Present after completion. Processing duration in milliseconds. Present after successful completion. ## Webhook callback mode Use callback mode when your backend should receive the final result automatically instead of polling. ```bash theme={null} curl -X POST "https://api.apixo.ai/api/v1/generateTask/cosyvoice-3-5-plus" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "request_type": "callback", "callback_url": "https://your-server.com/webhooks/apixo", "input": { "mode": "clone", "prefix": "demo01", "audio_urls": [ "https://example.com/reference.wav" ] } }' ``` See [Webhooks](/docs/api-reference/webhooks) for delivery requirements and retry behavior. ## Billing CosyVoice 3.5 Plus uses different billing units by workflow. | Workflow | APIXO price | | -------- | ------------------------ | | `speech` | `$0.25 / 10K characters` | | `clone` | `$0.002 / request` | | `design` | `$0.03 / request` | For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing). ## Latency and polling Actual latency may vary by text length, voice route, queue load, and whether you are creating a custom voice. | Workflow | Typical generation time | Recommended first poll | Poll interval | | -------- | ----------------------- | ----------------------- | ------------- | | `speech` | 5s-30s | 5s after task creation | 3s-5s | | `clone` | 30s-180s | 20s after task creation | 5s-10s | | `design` | 30s-180s | 20s after task creation | 5s-10s | Use callback mode for production voice creation workflows so your backend does not need to poll during longer `DEPLOYING` periods. This model does not expose built-in system voices through APIXO. Use a custom `voice_id` created by clone or design. Custom `voice_id` records are garbage-collected if they are not used for 7 consecutive days. If you plan to keep a custom voice active, call `speech` with that `voice_id` at least once within every 7-day window. ## Errors and troubleshooting ### HTTP errors | Code | Meaning | What to do | | ----- | --------------------------------------- | ------------------------------------ | | `400` | Invalid request body or parameter shape | Fix the request before retrying | | `401` | Missing or invalid API key | Check the `Authorization` header | | `402` | Insufficient balance or quota | Add balance or switch account/key | | `403` | Key or route cannot access the model | Check permissions and route strategy | | `429` | Rate limit or concurrency limit reached | Retry with exponential backoff | | `500` | Server error | Retry with backoff | | `502` | Upstream provider error | Retry with backoff | | `504` | Upstream timeout | Retry or use callback mode | ### Task failure cases | Fail code | Meaning | What to do | | ------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `UNDEPLOYED` | Voice review failed and the custom voice is unavailable | Create a new voice with better input audio or a different design prompt | | `TASK_TIMEOUT` | Custom voice deployment stayed in `DEPLOYING` for too long | Retry later | | `VALIDATION_ERROR` | Input failed APIXO validation, or a `voice_id` is invalid for the current user/provider/model | Fix the input before retrying | | `UpstreamError` | Upstream route returned an unmapped failure | Retry with backoff | Common validation rules: * `voice` is required for `speech`. APIXO also accepts legacy `voice_id` in the request and normalizes it into `voice`. * Built-in system voices are not available for `cosyvoice-3-5-plus`. * Custom `voice_id` values must belong to the current user, match the current provider, and match the target model. * Custom `voice_id` values are removed after 7 consecutive days without use. * `audio_urls` must be an array with exactly one non-empty URL. * `prefix` must be 1-10 letters or digits. * `instruction` must be at most 100 characters. ## Related links * [Generation API Overview](/docs/models) * [Generate Task](/docs/api-reference/generate-task) * [Status Task](/docs/api-reference/status-task) * [Webhooks](/docs/api-reference/webhooks) * [Error Codes](/docs/api-reference/errors) * [Pricing](https://apixo.ai/pricing)