# Botnoi API Guide for Developers & AI Agents

This document provides technical specifications for the Botnoi Voice, GenSub, and Voicebot APIs. It is optimized for programmatic integration and LLM context.

## Global Overview
- **Base URL**: `https://api-voice.botnoi.ai`
- **Region**: Thailand (Bangkok)
- **Primary Support**: Voice-as-a-Service, Transcription (ASR), and Programmatic Call Automation.

## Authentication
All API requests require a `botnoi-token` header. You can obtain your token from the [Botnoi Voice Developer Console](https://api-voice.botnoi.ai/api-developer-swagger).

**Header Example:**
```http
botnoi-token: <YOUR_API_TOKEN_HERE>
```
*Note: Do not use the "Bearer " prefix unless explicitly required by a specific endpoint.*

---

## 1. Voice API (Text-to-Speech)
**Base Host**: `https://api-voice.botnoi.ai`
**Purpose**: Generate high-quality human-like voices from text input.

**Title:** Generate Voice API
**Description:** API for generate voice from text
**Version:** 2

### `POST` /openapi/v1/generate_audio

**Summary:** Generate Voice V1
**Parameters:**
- `botnoi-token` (header): Authentication token for Botnoi API (Required)

**Request Body:**
- `Content-Type: application/json`
  - `text` (string): Text to generate (Required)
  - `speaker` (string): Speaker ID (Required)
  - `volume` (number): Float from 0.1 - 1.0 (Optional)
  - `speed` (number): Float from 0.3 - 2.0 (Optional)
  - `type_media` (string): Media format (e.g., "mp3") (Required)
  - `save_file` (string): Locked to "true" (Optional)
  - `language` (string): Language code (e.g., "th") (Optional)
  - `page` (string): Locked to "user" (Optional)
**Example Payload:**
```json
{
  "text": "สวัสดีครับ",
  "speaker": "1",
  "volume": 1,
  "speed": 1,
  "type_media": "mp3",
  "save_file": "true",
  "language": "th",
  "page": "user"
}
```

**Successful Response:**
```json
{
  "audio_url": "https://api-voice.botnoi.ai/example.mp3",
  "point": 6534,
  "user_monthly_point": 0
}
```

---

### `POST` /openapi/v1/generate_audio_v2

**Summary:** Generate Voice V2
**Parameters:**
- `botnoi-token` (header): Authentication token for Botnoi API (Required)

**Request Body:**
- `Content-Type: application/json`
  - `text` (string): Text to generate (Required)
  - `speaker` (string): Speaker ID (Required)
  - `volume` (number): Float from 0.1 - 1.0 (Optional)
  - `speed` (number): Float from 0.3 - 2.0 (Optional)
  - `type_media` (string): Media format (e.g., "mp3") (Required)
  - `save_file` (string): Locked to "true" (Optional)
  - `language` (string): Language code (e.g., "th") (Optional)
  - `page` (string): Locked to "user" (Optional)
**Example Payload:**
```json
{
  "text": "สวัสดีครับ",
  "speaker": "8",
  "volume": 1,
  "speed": 1,
  "type_media": "mp3",
  "save_file": "true",
  "language": "th",
  "page": "user"
}
```

**Successful Response:**
```json
{
  "audio_url": "https://api-voice.botnoi.ai/example.mp3",
  "point": 6534,
  "user_monthly_point": 0
}
```

---

### `GET` /openapi/v1/get_speaker_data

**Summary:** Get Speaker V1
**Successful Response:**
```json
[
  {
    "speaker_id": "3",
    "eng_name": "Ngam",
    "thai_name": "คุณงาม",
    "image": "https://bn-voice-pics.s3.ap-southeast-1.amazonaws.com/picture/ngam/ngam.webp",
    "audio": "https://botnoi-voice.s3.ap-southeast-1.amazonaws.com/picture/ngam/sound_ngam.wav",
    "voice_style": ["เสียงมั่นใจ"],
    "language": "TH",
    "gender": "Female",
    "price": 1.0
  }
]
```

---

### `GET` /openapi/v1/get_speaker_data_v2

**Summary:** Get Speaker V2
**Successful Response:**
```json
[
  {
    "speaker_id": "3",
    "eng_name": "Ngam",
    "thai_name": "คุณงาม",
    "image": "https://bn-voice-pics.s3.ap-southeast-1.amazonaws.com/picture/ngam/ngam.webp",
    "audio": "https://botnoi-voice.s3.ap-southeast-1.amazonaws.com/picture/ngam/sound_ngam.wav",
    "voice_style": ["เสียงมั่นใจ"],
    "language": "TH",
    "gender": "Female",
    "price": 1.0
  }
]
```

---

## GenSub API

**Title:** Botnoi GenAI API
**Description:** API for transcription, prompts, and audio management
**Version:** 1.0

### `POST` /gensub_json

**Parameters:**
- `botnoi-token` (header): Botnoi API Key (Required)
- `request` (body): JSON payload (Required)

**Example Payload:**
```json
{
  "audio_url": "https://example.com/audio.mp3",
  "language": "th"
}
```

**Successful Response:**
```json
{
  "data": {
    "current_monthly_point": 850,
    "current_point": 1200,
    "transcription": "Hello world"
  },
  "message": "Transcribe successfully"
}
```

---

### `POST` /gensub_upload

**Parameters:**
- `audio_file` (formData): Audio file (Required)
- `max_duration` (formData): Maximum chunk duration in seconds (Required)
- `max_silence` (formData): Maximum silence allowed in seconds (Required)
- `language` (formData): Language used for transcription (Required)
- `srt` (formData): Set to 'yes' for SRT response, or 'no' for plain text (Required)
- `botnoi-token` (header): Botnoi API Key (Required)

**Example Payload (Multipart/Form-Data):**
- `audio_file`: (Binary file)
- `max_duration`: "10"
- `max_silence`: "0.3"
- `language`: "th"
- `srt`: "yes"

**Successful Response:**
```json
{
  "data": {
    "current_monthly_point": 840,
    "current_point": 1190,
    "transcription": "Text from audio file"
  },
  "message": "Transcribe successfully"
}
```

---

## Voicebot API

**Title:** Botnoi Voicebot API
**Description:** API documentation for Voicebot.
**Version:** 1.0

### `POST` /confirm/call

**Parameters:**
- `botnoi-token` (header): Botnoi API Token (Required)
- `payload` (body): Outbound payload (Required)

**Example Payload:**
```json
{
  "speaker_id": "523",
  "Customer Name": "ชาติชาย",
  "Appointment Date": "31/07/2025",
  "Appointment Time": "10:00"
}
```

**Successful Response:**
```json
{
  "message": "OK",
  "call_id": "12345"
}
```
---

### `POST` /confirm/create_template

**Parameters:**
- `botnoi-token` (header): Botnoi authentication token (Required)
- `request` (body): Verification payload (Required)

**Example Payload:**
```json
{
  "message": "สวัสดีค่ะ จาก {Org_name} คุณมีนัดในวันที่ {Appointment Date} เวลา {Appointment Time} ต้องการยืนยันนัดหมายมั้ยคะ",
  "confirm_message": "ขอบคุณค่ะ คุณได้ยืนยันนัดหมายเรียบร้อยแล้ว เราจะรอคุณในวันที่ {Appointment Date} เวลา {Appointment Time} ค่ะ",
  "decline_message": "ขอบคุณค่ะ ยกเลิกนัดหมายเรียบร้อยแล้วนะคะ หากคุณ ต้องการเปลี่ยนแปลงนัดหมาย สามารถติดต่อกลับหาเราได้เลยนะคะ ขอบคุณค่ะ",
  "fallback_message": "ขอบคุณค่ะ หากคุณ ต้องการเปลี่ยนแปลงนัดหมาย สามารถแจ้งเราได้เลยนะคะ",
  "org_name": "บอทน้อย",
  "speaker_id": "523"
}
```

**Successful Response:**
```json
{
  "message": "Success Verify Outbound",
  "template_id": "temp_001"
}
```
---

## 4. Global Error Handling
Botnoi APIs use standard HTTP status codes. Most error responses follow this JSON structure:

**Error Response Example:**
```json
{
  "message": "Unauthorized - User not found",
  "status": "error"
}
```

### Common Error Codes:
- **400 Bad Request**: Missing required parameters or invalid JSON body.
- **401 Unauthorized**: Missing or invalid `botnoi-token`.
- **403 Forbidden**: Out of points or insufficient permissions.
- **422 Unprocessable Entity**: Validation error (e.g., text too long, invalid speaker ID).
- **500 Internal Server Error**: Unexpected server-side issue.

---

## 5. Integration Examples

### Python (Requests)
```python
import requests

url = "https://api-voice.botnoi.ai/openapi/v1/generate_audio"
payload = {
    "text": "สวัสดีครับ",
    "speaker": "1",
    "volume": 1,
    "speed": 1,
    "type_media": "mp3",
    "save_file": "true",
    "language": "th",
    "page": "user"
}
headers = {
    "botnoi-token": "YOUR_API_TOKEN",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

### Node.js (Axios)
```javascript
const axios = require('axios');

const generateVoice = async () => {
  const url = 'https://api-voice.botnoi.ai/openapi/v1/generate_audio';
  const data = {
    text: 'สวัสดีครับ',
    speaker: '1',
    volume: 1,
    speed: 1,
    type_media: 'mp3',
    save_file: 'true',
    language: 'th',
    page: 'user'
  };
  
  try {
    const response = await axios.post(url, data, {
      headers: { 'botnoi-token': 'YOUR_API_TOKEN' }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error.response.data);
  }
};
```

### cURL
```bash
curl -X POST https://api-voice.botnoi.ai/openapi/v1/generate_audio \
     -H "botnoi-token: YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "text": "สวัสดีครับ",
       "speaker": "1",
       "volume": 1,
       "speed": 1,
       "type_media": "mp3",
       "save_file": "true",
       "language": "th",
       "page": "user"
     }'
```