# AICU TTS API Skill

> ElevenLabs による高品質・多言語の音声合成。AiCuty 公式キャラクターボイス。同じ声×同じ文は何度でも無料（キャッシュ）。

## Package Info

- **Name**: aicu-tts
- **Version**: 0.2.0 (Alpha)
- **Base URL**: https://api.aicu.ai/v1
- **Auth**: APIキー必須 (Bearer Token)
- **Backend**: ElevenLabs（AiCuty 公式ボイス）

## Quick Start

### Generate Speech

```bash
curl -X POST https://api.aicu.ai/v1/audio/speech   -H "Authorization: Bearer aicu_live_xxx"   -H "Content-Type: application/json"   -d '{"input": "こんにちは、AICUです", "voice": "nao"}'   --output voice.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

**文字数で課金します**（仕入れの ElevenLabs と同じ単位）。**いまの単価は `GET /v1/models` の `tts` の `pricing`** が返します。
2026-09-09 に 1,000 文字 = 200 AP で始まり、**毎週水曜 05:00 UTC に少しずつ上がります**（改定は [News](https://api.aicu.ai/news) に載ります）。**キャラクターのライセンスは解決済み**です。

- 同じ声×同じ文の再生成はキャッシュから返るので **0 AP**（何度でも無料）
- 消費 AP は毎回 `X-AICU-AP-Cost` で返ります。見積もりは「文字数 ÷ 1,000 × 単価」で（**秒数ではありません**）
- 1 USD = 10,000 AP

## 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

---

## Japanese readings & v3 audio tags（日本語の読み・感情タグ）

- **読みの矯正はサーバ側で既定適用**（`AICU`→「アイキュー」等の辞書 `lib/yomi.ts`。日本語を含むテキストにだけ効く）。固有名詞の誤読は**送る前にかな書きに置換**するのが最も確実
- **抑揚・感情は `model: "eleven_v3"` のオーディオタグだけが触れる**（`[whispers]` `[excited]` 等）。発音辞書では変えられない。タグの効き方は声ごとに違うので、使う声で実測する
- 手引き（実測つき）: https://api.aicu.ai/docs/japanese-tts/ （日本語版 https://api.aicu.ai/docs/ja/japanese-tts/ ）。v3 互換面の呼び方は https://api.aicu.ai/docs/api/ の `/v1/el/tts`

## Best Practices

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

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

---
*AICU Inc. - 2026-09-29*