API Documentation

Complete reference for the ArtHub AI API services

Interactive API Reference

Try out API endpoints directly in your browser with our Scalar-powered docs

Open API Reference

Quick Start

Get started with the ArtHub API in minutes

1. Create an Account

2. Generate an API Key

Create an API key from your dashboard. Keep it secure!

3. Make Your First Request

Create a TTS task using your API key:

curl -X POST "https://api.arthub.ai/api/v1/tasks/voice/tts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "text": "Hello, welcome to ArtHub AI!",
    "voice_id": "story_492c545d30ac4d988869845c83d4a7af_char_char_64877738",
    "language": "en"
  }'

4. Check Task Status

Poll for the result using the task_id:

curl "https://api.arthub.ai/api/v1/tasks/{task_id}" \
  -H "X-API-Key: your_api_key_here"

# Response when completed:
{
  "status": "completed",
  "progress": { "percentage": 100 },
  "output": {
    "audio_url": "/storage/audio/output.wav"
  }
}

Authentication

API Key Authentication

For API service endpoints (tasks), include your API key in the header:

X-API-Key: ak_your_api_key_here

JWT Authentication

For account management endpoints, use the JWT bearer token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

OpenAI-Compatible TTS API

Drop-in replacement for OpenAI /v1/audio/speech. Dùng trực tiếp với OpenAI SDK — chỉ cần đổi base_url và api_key.

Base URLhttps://api.arthub.ai/v1

AuthAuthorization: Bearer ak_your_api_key

POST/v1/audio/speechBearer

Generate speech from text (OpenAI-compatible). Returns binary audio.

Request Body

{
  "model": "tts-1",
  "input": "Hello, welcome to ArtHub AI!",
  "voice": "alloy",
  "response_format": "mp3",
  "speed": 1
}

💡 Response is binary audio (not JSON). Content-Type depends on response_format.

GET/v1/audio/voicesNone

List available voices with OpenAI name → ArtHub mapping

Response

{
  "voices": [
    {
      "voice": "alloy",
      "name": "Adam",
      "arthub_voice_id": "arthub_en_male_01",
      "gender": "male",
      "description": "Engaging, friendly and bright"
    },
    {
      "voice": "nova",
      "name": "Annie",
      "arthub_voice_id": "arthub_en_female_01",
      "gender": "female",
      "description": "Bright, clear, and engaging"
    }
  ]
}

Request Parameters

Field	Required	Type	Description
model	Yes	string	`tts-1` hoặc `tts-1-hd`
input	Yes	string	Text cần chuyển thành giọng nói (tối đa 4096 ký tự)
voice	Yes	string	Tên voice OpenAI hoặc ArtHub voice_id
response_format	No	string	`mp3` (mặc định), `wav`, `opus`, `aac`, `flac`, `pcm`
speed	No	number	0.25 – 4.0 (mặc định 1.0)

Voice Mapping

Mapping từ OpenAI voice name sang ArtHub voice. Ngoài 9 voice chuẩn, có thể truyền trực tiếp ArtHub voice_id (vd: arthub_en_female_03).

OpenAI Voice	ArtHub Voice	Gender	Description
alloy	Adam	Male	Engaging, friendly and bright
ash	Dave	Male	Expressive and vibrant
coral	Callie	Female	Playful, inviting and friendly
echo	Max	Male	E-learning and documentary
fable	Danielle	Female	Gentle and engaging narrator
onyx	David Boles	Male	Well-spoken and calm
nova	Annie	Female	Bright, clear, and engaging
sage	Jerry B	Male	Realistic and conversational
shimmer	Zara	Female	Warm, real-world conversationalist

Code Examples

Sử dụng trực tiếp với OpenAI SDK hoặc curl

curl

curl https://api.arthub.ai/v1/audio/speech \
  -H "Authorization: Bearer ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello from ArtHub TTS!",
    "voice": "nova"
  }' --output speech.mp3

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.arthub.ai/v1",
    api_key="ak_your_api_key",
)

response = client.audio.speech.create(
    model="tts-1",
    voice="alloy",
    input="Xin chào từ ArtHub TTS!",
)
response.stream_to_file("speech.mp3")

Node.js (OpenAI SDK)

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  baseURL: "https://api.arthub.ai/v1",
  apiKey: "ak_your_api_key",
});

const response = await client.audio.speech.create({
  model: "tts-1",
  voice: "nova",
  input: "Hello from ArtHub TTS!",
});

const buffer = Buffer.from(await response.arrayBuffer());
await fs.promises.writeFile("speech.mp3", buffer);

Python (requests)

import requests

response = requests.post(
    "https://api.arthub.ai/v1/audio/speech",
    headers={
        "Authorization": "Bearer ak_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "model": "tts-1",
        "input": "Hello from ArtHub!",
        "voice": "alloy",
        "response_format": "mp3",
    },
)

with open("speech.mp3", "wb") as f:
    f.write(response.content)

Error Response Format

Lỗi trả về theo chuẩn OpenAI

{
  "error": {
    "message": "Unknown voice 'xyz'. Supported: alloy, ash, coral, echo, fable, nova, onyx, sage, shimmer.",
    "type": "invalid_request_error",
    "param": "voice",
    "code": "voice_not_found"
  }
}

Error Type	HTTP	Nguyên nhân
authentication_error	401	Thiếu hoặc sai API key
permission_error	403	API key không có quyền voice:tts hoặc bị chặn IP
invalid_request_error	400	Sai model, voice, hoặc format
server_error	500	Lỗi server khi tạo audio

Task Status Flow

Understanding the task lifecycle

pending→

processing→

completed

pending: Task created, waiting to be processed

processing: Task is being executed (check progress.percentage)

completed: Task finished, output available in response

failed: Task failed, check error.code and error.message

Rate Limits

Limit Type	Default	Description
Per Minute	60 requests	Configurable per API key
Per Day	1,000 requests	Configurable per API key
Monthly Budget	Unlimited	Optional spending limit

Error Codes

Code	HTTP Status	Description
INSUFFICIENT_BALANCE	402	Not enough balance
INVALID_API_KEY	401	API key is invalid
RATE_LIMIT_EXCEEDED	429	Too many requests
PROCESSING_ERROR	500	Server processing error