Text-to-Speech API

Version requirement: Pro and above

Introduction

The text-to-speech API converts text content into audio files, with multiple voice options available for various scenarios including general Q&A, intelligent assistants, audiobooks, video narration, and regional accents.

Online API testing: API Debug Console

API Definition

Endpoint

POST https://api.linkai.cloud/v1/audio/speech

Request Headers

Parameter	Value	Description
Authorization	Bearer YOUR_API_KEY	Create an API Key following Authentication
Content-Type	multipart/form-data	Indicates form data format for uploading audio files

Request Body

Parameter	Type	Required	Description
input	string	Yes	Text content to be converted to speech
app_code	string	No	Agent code, if provided, the voice configured in the Agent will be used
voice	string	No	Voice code, see Voice List for all available voices

Note: At least one of app_code or voice must be non-empty. If app_code is provided, the voice configured in the Agent will be used, and there's no need to provide the voice parameter. If the voice parameter is provided, the specified voice will be used directly, without needing to set the app_code parameter.

You can configure the voice bound to an Agent in "Agent - Model Settings - Voice":

Response

The response is output as a binary stream, which can be saved as a file for playback.

Error Handling

When an error occurs, the API returns the following structure:

{
    "success": false,
    "code": 408,
    "message": "No API access permission for current version",
    "data": null
}

Determine the error type based on the HTTP status code and error message:

HTTP Status Code	Description
400	Invalid request format
401	Authentication failed, please check if your API Key is correct
402	Agent does not exist, please check if the app_code parameter is correct
403	No access permission, for private Agents, only the creator account can call
406	Insufficient account credits
408	No API access permission, this API supports Pro version and above
409	Content moderation failed, sensitive content may exist in the question, answer, or knowledge base
503	API call exception, please contact customer service

Example Code

1. CURL Request

curl https://api.linkai.cloud/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello, how can I help you?",
    "voice": "BV700_V2_streaming"
  }' \
  --output speech.mp3

Note: Replace YOUR_API_KEY with your created API Key, and provide the local path for the audio file in the file parameter.

2. Python Code

import requests
url = 'https://api.linkai.cloud/v1/audio/speech'
headers = {
    'Authorization': f'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'input': 'Hello, how can I help you?',
    'voice': 'BV007_streaming'
}
res = requests.post(url, headers=headers, json=data)
file_path = "speech.mp3"
if res.status_code == 200:
    with open(file_path, 'wb') as f:
        f.write(res.content)
    print(f"Speech synthesis successful, audio file: {file_path}")
else:
    error = res.json()
    print(f"Request error, status code={error.get('code')}, error message={error.get('message')}")

Note: Replace YOUR_API_KEY with your created API Key, and provide the local path for the audio file in the file_path variable.