Name: Kokoro v1.0 – AI Text to Speech | Free · $5/mo | API.market
Brand: magicapi
SKU: api-magicapi-ai-text-to-speech-generator
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# 🗣️ Ultra-Natural Text-to-Speech API (Kokoro v1.0)

## Overview
The Ultra-Natural Text-to-Speech API (Kokoro v1.0) enables you to instantly convert text into expressive, human-like speech in real time. Powered by an advanced AI with 82 million parameters, this service delivers high-quality voice output for all your voice-driven applications—be it audiobooks, assistive technology, or interactive chatbots.

Kokoro v1.0 is built on a next-generation architecture that excels in audio clarity, natural intonation, and consistent voice quality, making it ideal for projects that demand engaging, human-sounding speech.

## Features
- Transforms text into rich, realistic speech using an 82M-parameter AI model.
- Multiple voice options spanning different languages and styles.
- Adjustable speech speed (0.5x to 5.0x).
- Automatic handling of long text by splitting it into manageable chunks.
- Designed for production-scale workloads and reliable, asynchronous processing.

## Use Cases
1. Education & E-Learning: Generate audio lessons or narrations for student materials, ensuring even large text loads are spoken in a natural voice.  
2. Broadcast & Media: Automate voice overs for news, podcasts, or advertising content.  
3. Customer Support & IVR: Provide phone or chatbot services with natural, human-like responses to user queries.  
4. Accessibility Tools: Aid visually impaired users by converting text from websites or documents into real-time audio.  
5. Entertainment & Gaming: Bring in-game characters to life with dynamic, realistic voice lines pulled directly from generated text.

## Visual Examples
Below is a sample output URL from a successful text-to-speech request, returning a .wav file. This demonstrates how the API delivers a direct audio link upon completion:

![Audio example of synthesized speech output](https://replicate.delivery/czjl/ZpQ6y6VCoBZcDxuWJbp9rwXgTbUhgVUzwRn2iDiTXSxpZhCF/output.wav)

Feel free to click or download it in your browser to preview the voice output generated by Kokoro v1.0.  

## Pricing
- 1 API unit equals 1 text-to-speech request processed.  
- GET requests to check prediction status (GET /api/v1/magicapi/ai-text-to-speech-generator/predictions/{id}) are free and do not count toward your usage.  
- Different pricing tiers are available based on usage volume. For details on the various tiers, please visit API.market pricing or contact us for a custom plan.

## API Documentation

### Base URL
All requests should be sent to:  
```
https://prod.api.market/api/v1/magicapi/ai-text-to-speech-generator
```

### Authentication
Include your API key in the request header:

```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API processes text-to-speech requests asynchronously. The typical workflow is:

1. Submit a POST request to the /predictions endpoint with your desired parameters (text, voice, speed, etc.).  
2. You’ll receive a response containing a unique prediction ID.  
3. Poll the GET /predictions/{id} endpoint to check the status of your request:  
   - While the status is "starting" or "processing", the synthesis is still in progress.  
   - Once the status is "succeeded", your completed audio file URL is provided in the "output" field.  
   - If the status is "failed", review the "error" field for details.  
4. Implement a 1-second polling interval and a maximum timeout of 600 seconds (10 minutes) to avoid indefinite waiting.

### Endpoints

#### 1. Create a Prediction
• HTTP Method: POST  
• Endpoint: /api/v1/magicapi/ai-text-to-speech-generator/predictions  
• Description: Creates a new text-to-speech prediction.

Example Request (JSON):
```json
{
  "version": "f559560eb822dc509045f3921a1921234918b91739db4bf3daab2169b71c7a13",
  "input": {
    "text": "Hello world! This is Kokoro speaking at 1x speed using the nicole voice.",
    "speed": 1,
    "voice": "af_nicole"
  }
}
```

Example cURL:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-text-to-speech-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "f559560eb822dc509045f3921a1921234918b91739db4bf3daab2169b71c7a13",
    "input": {
      "text": "Hello world! This is Kokoro speaking at 1x speed using the nicole voice.",
      "speed": 1,
      "voice": "af_nicole"
    }
  }'
```

Example Response (JSON):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "f559560eb822dc509045f3921a1921234918b91739db4bf3daab2169b71c7a13",
  "status": "starting",
  "created_at": "2025-05-18T08:04:46.184Z"
}
```

#### 2. Get Prediction Status/Result
• HTTP Method: GET  
• Endpoint: /api/v1/magicapi/ai-text-to-speech-generator/predictions/{id}  
• Description: Checks the status of an existing prediction by ID. Returns the status, any errors, and the final audio URL if complete.

Example Request:
```
GET /api/v1/magicapi/ai-text-to-speech-generator/predictions/ufawqhfynnddngldkgtslldrkq
```

Example cURL:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-text-to-speech-generator/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

Example Response (JSON):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://replicate.delivery/czjl/ZpQ6y6VCoBZcDxuWJbp9rwXgTbUhgVUzwRn2iDiTXSxpZhCF/output.wav",
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

## Status Codes
- 200 OK: Request successful.  
- 201 Created: Resource successfully created (e.g., new prediction).  
- 400 Bad Request: Invalid input parameters or malformed request.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: Valid API key but insufficient permissions.  
- 404 Not Found: Specified resource (prediction ID) not found.  
- 429 Too Many Requests: Rate limit exceeded. Slow down or upgrade your plan.  
- 500 Internal Server Error: An error occurred on the server side.  
- 503 Service Unavailable: Service temporarily unavailable.

## Rate Limits
All requests are subject to rate limits to ensure quality of service. If you exceed the rate limit, you may receive a 429 Too Many Requests response. We recommend implementing exponential backoff or a 1-second delay before retrying.

## Error Handling
When the API encounters an error, you’ll receive a JSON response with details:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'text' is required",
    "status": 400
  }
}
```

Common issues include:  
- Missing required fields (e.g., "text")  
- Invalid API key  
- Exceeding rate limits  

Always check the returned HTTP status code and error message for guidance on resolving the issue. If your request consistently fails, contact support.

## Implementation Guide

Below are example implementations of how to integrate with this API, showing the asynchronous process of creating a prediction and then polling until the final output is ready.

### JavaScript (Node.js) Example
```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-text-to-speech-generator";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({
        version: "f559560eb822dc509045f3921a1921234918b91739db4bf3daab2169b71c7a13",
        input: inputData
      })
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second

  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-magicapi-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}
```

### Python Example
```python
# Python example with proper polling and timeout
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-text-to-speech-generator"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    
    data = {
        "version": "f559560eb822dc509045f3921a1921234918b91739db4bf3daab2169b71c7a13",
        "input": input_data
    }
    
    response = requests.post(f"{BASE_URL}/predictions", headers=headers, json=data)
    
    if response.status_code != 201 and response.status_code != 200:
        raise Exception(f"API error: {response.status_code} {response.text}")
    
    prediction = response.json()
    prediction_id = prediction["id"]

    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second

    headers = {"x-magicapi-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)
        
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")
        
        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]
        elif prediction["status"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")

        time.sleep(POLL_INTERVAL)

    raise Exception("Prediction timed out after 10 minutes")
```

### cURL Example
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-text-to-speech-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "f559560eb822dc509045f3921a1921234918b91739db4bf3daab2169b71c7a13",
    "input": {
      "text": "Hello from cURL!",
      "speed": 1,
      "voice": "af_nicole"
    }
  }'

# Example response:
# {
#   "id": "ufawqhfynnddngldkgtslldrkq",
#   "status": "starting",
#   "created_at": "2025-05-18T08:04:46.184Z"
# }

# Step 2: Poll the GET endpoint until status is "succeeded"
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-text-to-speech-generator/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Consolidate text into meaningful batches to reduce the number of requests.  
- Adjust the speech speed parameter judiciously; extremely high or low speeds may affect performance.  
- Cache or reuse audio results if your text input is repeated frequently.  
- Use exponential backoff or short delays between calls to avoid triggering rate limits unnecessarily.

## FAQ
1. **Why is my output taking a long time?**  
   Large volumes of text or high concurrency may increase processing times. Use batching and polling to optimize throughput.

2. **How do I choose the best voice?**  
   The API offers multiple voices in different languages and accents. Use the voice parameter to experiment and pick the one that best suits your brand or project.

3. **Can I adjust speaking style or emotion?**  
   At present, you can control the speech speed. The model’s inherent voice style is tied to the chosen voice parameter.

4. **Is there a limit on text length?**  
   Very long text is automatically split and processed in segments. Each segment remains in sequence within the final output.

5. **How do I handle rate limit errors (429)?**  
   Implement short pauses or exponential backoff between requests. Contact us if you consistently need higher throughput.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello[at]api.market.

Convert text to expressive, human-like speech. Features an 82M parameter AI model. Free 20 calls/mo, from $4.99/mo. Start free on API.market.

Kokoro v1.0 – AI Text to Speech | Free · $5/mo | API.market

🗣️ Ultra-Natural Text-to-Speech API (Kokoro v1.0)

FREE

MagicAPI

PAYG

START

ULTRA

ELITE

MEGA

GIGA

BULK

Convert text to expressive, human-like speech in real time with Kokoro's advanced 82M parameter AI—perfect for voice apps, content, and accessibility.