# AICU TTS API Skill

> 高品質な日本語音声合成API。同じセリフは何度再生しても無料。

## Package Info

- **Name**: aicu-tts
- **Version**: 0.2.0 (Alpha)
- **Base URL**: https://api.aicu.ai/v1
- **Auth**: APIキー必須 (Bearer Token)
- **Backend**: Qwen3-TTS on fal.ai GPU

## Quick Start

### Generate Speech

```bash
curl -X POST https://api.aicu.ai/v1/tts/generate \
  -H "Authorization: Bearer aicu_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "こんにちは", "slug": "luc4"}' \
  --output hello.mp3
```

### List Voices

```bash
curl https://api.aicu.ai/v1/tts/voices \
  -H "Authorization: Bearer aicu_live_xxx"
```

## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| text | string | Yes | Text to speak (max 5000 chars) |
| slug | string | No | Character slug (e.g., "luc4") |
| voice | string | No | Speaker ID |
| format | string | No | mp3, wav (default: mp3) |
| instruct | string | No | Style instruction (English) |
| seed | number | No | Reproducibility seed |
| force | boolean | No | Bypass cache |

## Characters

| slug | Name | Voice | Status |
|------|------|-------|--------|
| luc4 | LuC4 | aiden | public |

## Voices

| ID | Name | Language |
|----|------|----------|
| ono_anna | 小野杏奈 | Japanese |
| vivian | Vivian | English |
| serena | Serena | English |
| aiden | Aiden | English |

## Response Headers

- `X-Cache-Hit`: "true" on cache hit
- `X-Slug`: Character used
- `X-Credits-Used`: AP consumed (0 on cache hit)
- `X-Credits-Remaining`: Remaining AP
- `X-TTS-Latency-Ms`: TTS generation latency

## Pricing

- **10 seconds = 1 AP = ¥0.01**
- Charged by audio duration (not input length)
- **Cache hit = FREE**
- No charge on failure

## TypeScript Example

```typescript
async function speak(text: string): Promise<ArrayBuffer> {
  const response = await fetch('https://api.aicu.ai/v1/tts/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.AICU_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text,
      slug: 'luc4',
      format: 'mp3',
    }),
  });

  if (!response.ok) throw new Error(`TTS Error: ${response.status}`);
  return response.arrayBuffer();
}
```

## Instruct Examples

Control speech style with English instructions:

```json
{"instruct": "Speak with energy and excitement"}
{"instruct": "Whisper softly"}
{"instruct": "Speak calmly like a narrator"}
{"instruct": "Read slowly and clearly"}
```

## Error Codes

| Code | Description |
|------|-------------|
| 401 | Invalid API key |
| 402 | Insufficient credits |
| 429 | Rate limited |
| 500 | TTS generation error |

## Rate Limits

| Plan | Requests/min |
|------|-------------|
| Free | 2 |
| Starter | 10 |
| Creator | 20 |

## API Key

Get your API key at: https://api.aicu.ai/dashboard/keys

## Support

- Dashboard: https://api.aicu.ai/dashboard
- Docs: https://api.aicu.ai/docs

---

## Best Practices

**キャッシュを活用**:
- 定型挨拶（「こんにちは」「ありがとう」）は初回生成後、無料
- 同じtext + voice + seedでキャッシュヒット

**force パラメータ**:
- 声の微調整時は `force: true` でキャッシュをバイパス
- 本番では `force: false` (デフォルト) でコスト削減

---
*AICU Japan K.K. - 2026-05-13*