> ## 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.

# MiniMax Voice API

> MiniMax custom voice creation API for reusable voice design and voice clone workflows

## Overview

MiniMax Voice is an audio model for creating reusable custom voices. Use `design` to create a new voice from a text description, or use `clone` to create a reusable voice from one reference audio clip.

| Capability                 | Value                                            |
| -------------------------- | ------------------------------------------------ |
| Model ID                   | `minimax-voice`                                  |
| Modes                      | `design`, `clone`                                |
| Built-in voices            | No                                               |
| Custom voices              | Yes                                              |
| Voice ID source            | Generated by the platform from `voice_id_prefix` |
| Design preview text length | 1-500 characters                                 |
| Clone preview text length  | 1-2000 characters when provided                  |
| 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/minimax-voice`               | Submit a design or clone task         |
| `GET`  | `/statusTask/minimax-voice?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 clone task and returns a `taskId`.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/minimax-voice" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "clone",
      "voice_id_prefix": "warm001",
      "audio_urls": [
        "https://example.com/reference.wav"
      ],
      "preview_text": "Hello, this is a cloned voice preview.",
      "need_noise_reduction": true,
      "need_volume_normalization": true,
      "accuracy": 0.7,
      "language_boost": "Chinese"
    }
  }'
```

Successful response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "processing",
    "voice_id": "warm001-a1b2c3",
    "voice_type": "preparing"
  }
}
```

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/minimax-voice?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": "warm001-a1b2c3",
    "voice_type": "preparing",
    "createTime": 1781502331739
  }
}
```

Success response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "voice_id": "warm001-a1b2c3",
    "voice_type": "active",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/temp/preview.mp3\"]}",
    "createTime": 1781502331739,
    "completeTime": 1781502332542,
    "costTime": 803
  }
}
```

Failed response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "voice_id": "warm001-a1b2c3",
    "failCode": "VALIDATION_ERROR",
    "failMsg": "Reference audio validation failed.",
    "createTime": 1781502331739,
    "completeTime": 1781502332542
  }
}
```

Parse `resultJson` after `state` becomes `success`:

```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const audioUrls = payload.resultUrls;
```

## Request body

### Design

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "design",
    "voice_id_prefix": "warm001",
    "prompt": "A warm and calm female narration voice for product explainers.",
    "preview_text": "Hello, welcome to our product demo."
  }
}
```

### Clone

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "clone",
    "voice_id_prefix": "warm001",
    "audio_urls": [
      "https://example.com/reference.wav"
    ],
    "preview_text": "Hello, this is a cloned voice preview.",
    "need_noise_reduction": true,
    "need_volume_normalization": true,
    "accuracy": 0.7,
    "language_boost": "Chinese"
  }
}
```

## Parameters

<ParamField body="request_type" type="string" required default="async">
  Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
</ParamField>

<ParamField body="callback_url" type="string">
  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).
</ParamField>

<ParamField body="input" type="object" required>
  MiniMax Voice input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="string" required>
      Workflow type. Supported values: `design`, `clone`.
    </ParamField>

    <ParamField body="voice_id_prefix" type="string" required>
      Required for both modes. Used to generate the final reusable `voice_id`. Must start with a letter, contain only letters or digits, and be at least 6 characters long.
    </ParamField>

    <ParamField body="prompt" type="string">
      Required for `design`. Voice description text used to create the custom voice.
    </ParamField>

    <ParamField body="preview_text" type="string">
      Required for `design` and limited to 500 characters. Optional for `clone` and limited to 2000 characters when provided.
    </ParamField>

    <ParamField body="audio_urls" type="string[]">
      Required for `clone`. Must contain exactly 1 non-empty, publicly reachable audio URL.
    </ParamField>

    <ParamField body="need_noise_reduction" type="boolean">
      Optional for `clone`. Enables noise reduction on the reference audio.
    </ParamField>

    <ParamField body="need_volume_normalization" type="boolean">
      Optional for `clone`. Enables volume normalization on the reference audio.
    </ParamField>

    <ParamField body="accuracy" type="number">
      Optional for `clone`. Must be between `0` and `1`.
    </ParamField>

    <ParamField body="language_boost" type="string">
      Optional for `clone`. Supported values: `Chinese`, `Chinese,Yue`, `English`, `Arabic`, `Russian`, `Spanish`, `French`, `Portuguese`, `German`, `Turkish`, `Dutch`, `Ukrainian`, `Vietnamese`, `Indonesian`, `Japanese`, `Italian`, `Korean`, `Thai`, `Polish`, `Romanian`, `Greek`, `Czech`, `Finnish`, `Hindi`, `auto`.
    </ParamField>
  </Expandable>
</ParamField>

## Voice ID behavior

* The final `voice_id` is generated automatically from `voice_id_prefix`.
* A typical returned value looks like `warm001-a1b2c3`.
* Use the returned `voice_id` in later MiniMax speech generation requests that support custom voices.
* If you want to keep a newly created custom voice available for long-term reuse, use that `voice_id` in a supported speech request after creation.
* A newly created custom voice that is never used later may become unavailable after 7 days.

## Validation and media rules

* Only the documented fields on this page are part of the public request contract.
* Do not send your own final `voice_id` in the request; the platform generates it for you.
* Clone requires exactly 1 reference audio URL.
* Reference audio URLs must be publicly reachable.
* Supported reference audio formats include `mp3`, `m4a`, and `wav`.
* Clear speech works best. Heavy background music, strong noise, long silence, or invalid audio content can cause the task to fail.
* The preview synthesis model for clone mode is platform-managed and is not user-selectable.

## Response format

### Submit task response

`POST /generateTask/minimax-voice` returns a task ID when the task is accepted:

<ResponseField name="code" type="integer">
  API status code. `200` means the task was accepted.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="data.taskId" type="string">
  Unique task identifier used with the status endpoint.
</ResponseField>

### Status response fields

<ResponseField name="taskId" type="string">
  Unique task identifier.
</ResponseField>

<ResponseField name="state" type="string">
  Current task state: `processing`, `success`, or `failed`.
</ResponseField>

<ResponseField name="voice_id" type="string">
  Reusable custom voice ID generated for this task.
</ResponseField>

<ResponseField name="voice_type" type="string">
  Voice readiness state. `preparing` means the custom voice is still being prepared; `active` means it was created successfully.
</ResponseField>

<ResponseField name="resultJson" type="string">
  JSON string containing preview audio result URLs. Present when preview audio is available.
</ResponseField>

<ResponseField name="failCode" type="string">
  Machine-readable failure code. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="failMsg" type="string">
  Human-readable failure message. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="createTime" type="integer">
  Task creation timestamp in Unix milliseconds.
</ResponseField>

<ResponseField name="completeTime" type="integer">
  Task completion timestamp in Unix milliseconds. Present after completion.
</ResponseField>

<ResponseField name="costTime" type="integer">
  Processing duration in milliseconds. Present after successful completion.
</ResponseField>

## 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/minimax-voice" \
  -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": "design",
      "voice_id_prefix": "warm001",
      "prompt": "A warm and calm female narration voice for product explainers.",
      "preview_text": "Hello, welcome to our product demo."
    }
  }'
```

See [Webhooks](/docs/api-reference/webhooks) for delivery requirements and retry behavior.

## Billing

MiniMax Voice is billed per request.

| Workflow | APIXO price       |
| -------- | ----------------- |
| `design` | `$0.50 / request` |
| `clone`  | `$0.50 / request` |

For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).

## Latency and polling

Voice creation usually takes longer than lightweight TTS requests because the custom voice must be prepared before it can be reused.

| Workflow | Recommended first poll  | Poll interval |
| -------- | ----------------------- | ------------- |
| `design` | 10s after task creation | 5s-10s        |
| `clone`  | 10s after task creation | 5s-10s        |

<Tip>
  Use callback mode for production voice-creation workflows so your backend does not need to keep polling.
</Tip>

## 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` | Provider-side error during voice creation | Retry with backoff                   |
| `504` | Voice creation timeout                    | Retry or use callback mode           |

### Common validation and failure cases

* `voice_id_prefix` must start with a letter, contain only letters or digits, and be at least 6 characters long.
* `preview_text` is required for `design`, and cannot be empty.
* `audio_urls` must contain exactly one non-empty URL for `clone`.
* `need_noise_reduction` and `need_volume_normalization` must be boolean values when provided.
* `accuracy` must be between `0` and `1`.
* `language_boost` must be one of the documented supported values.
* Reference audio that is unreachable, empty, too noisy, or otherwise invalid can cause task failure.

## Related links

* [Generation API Overview](/docs/models)
* [Audio Models](/docs/models/audio)
* [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)
* [Try MiniMax Voice in the APIXO Playground](https://apixo.ai/models/minimax-voice)
* [Pricing](https://apixo.ai/pricing)