# AICU LLM API Skill

> OpenAI互換のLLM API。APIキー（`llm` スコープ）が必要です。

## Package Info

- **Name**: aicu-llm
- **Version**: 0.2.0 (Beta)
- **Base URL**: https://api.aicu.ai/v1
- **Auth**: APIキー必須 (Bearer Token、`llm` スコープ)

---

## Quick Start

APIキーを発行してから利用します。モデル一覧は認証不要で確認できます。

```bash
# 利用可能なモデル一覧（認証不要）
curl https://api.aicu.ai/v1/chat/models

# チャット補完（APIキー必須）
curl -X POST https://api.aicu.ai/v1/chat/completions \
  -H "Authorization: Bearer $AICU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-v3", "messages": [{"role": "user", "content": "Hello"}]}'
```

---

## Available Models

| Model | Cost | Stage | Description |
|-------|------|-------|-------------|
| groq-llama-3.3-70b | 0 AP (free) | alpha | 高品質、レート制限あり |
| groq-llama-3.1-8b | 0 AP (free) | alpha | 高速、レート制限あり |
| deepseek-v3 | 14 AP/1K tokens | beta | 汎用、コスパ良好 |
| gemini-flash | 6 AP/1K tokens | beta | 軽量・低コストの Gemini。大量処理・定型タスク向け（原価×3） |
| llama-3.1-8b | 2 AP/1K tokens | beta | 軽量 |
| llama-3.1-70b | 6 AP/1K tokens | beta | 高品質 |
| qwen3-32b | 5 AP/1K tokens | beta | 大規模コンテキスト |
| gpt-4o | 132 AP/1K tokens | beta | OpenAI 高品質マルチモーダル（Alpha無料） |
| gpt-4o-mini | 8 AP/1K tokens | beta | OpenAI 軽量・高速（Alpha無料） |
| sakura-kimi | 60 AP/1K tokens | alpha | 国産推論 さくらのAI Engine 上の Kimi-K2.6（マルチモーダル・reasoning）。推論は国内・学習に不使用。 |
| gpt-5 | 113 AP/1K tokens | alpha | 最上位。推論が要る作業向け。入力は gpt-4o の半額、出力は同額（旧世代。新規は gpt-5.6 系を推奨） |
| gpt-5-mini | 23 AP/1K tokens | alpha | gpt-5 の 1/5。gpt-4o-mini より賢く、gpt-4o より大幅に安い（旧世代。新規は gpt-5.6 系を推奨） |
| gpt-5-nano | 5 AP/1K tokens | alpha | 最安の GPT-5。分類・抽出など定型の作業向け（旧世代。新規は gpt-5.6 系を推奨） |
| gpt-5.6-sol | 300 AP/1K tokens | alpha | 最上位。難しい推論・長い文脈向け |
| gpt-5.6-terra | 160 AP/1K tokens | alpha | sol の半額。日常的な作業の主力 |
| gpt-5.6-luna | 60 AP/1K tokens | alpha | 軽量で速い。対話・要約向け |
| gpt-5.4-mini | 50 AP/1K tokens | alpha | 安価。定型の生成や抽出向け |
| gpt-5.4-nano | 14 AP/1K tokens | alpha | 最安。分類・判定など短い作業向け |
| kimi-k2.7-code | 101 AP/1K tokens | preview | さくらのAI Engine 上の Kimi-K2.7-Code。コーディング特化・マルチモーダル（パブリックプレビュー）。OpenCode/Cline 等の OpenAI 互換ツールから利用可。国内推論・学習不使用。 |
| gemini-3.6-flash | 90 AP/1K tokens | beta | 最新の Gemini 3.6 Flash。高品質マルチモーダル。高度な推論・長い文脈向け（原価×3） |

**おすすめ**:
- `kimi-k2.7-code` - コーディング特化、国内推論（OpenCode/Cline/Continue 等で利用可）
- `deepseek-v3` - 汎用、コスパ最強
- `groq-llama-3.3-70b` - 無料、高品質（レート制限あり）

---

## API Key

1. ダッシュボードでログイン: https://api.aicu.ai/dashboard/keys
2. 新しい API キーを作成（`llm` スコープが必要）
3. 発行された `aicu_live_xxx` を `Authorization: Bearer <key>` として送信

`GET /v1/chat/models` のみ認証不要です。それ以外の LLM エンドポイントは 401 を返します。

---

## OpenAI SDK Integration

既存のOpenAI SDKをそのまま使えます。

### Python
```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.aicu.ai/v1",
    api_key=os.environ["AICU_API_KEY"],
)

response = client.chat.completions.create(
    model="deepseek-v3",
    messages=[{"role": "user", "content": "こんにちは"}]
)
print(response.choices[0].message.content)
```

### TypeScript
```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.aicu.ai/v1',
  apiKey: process.env.AICU_API_KEY,
});

const response = await client.chat.completions.create({
  model: 'deepseek-v3',
  messages: [{ role: 'user', content: 'こんにちは' }],
});
```

---

## API Reference

### POST /v1/chat/completions

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| model | string | Yes | モデルID (例: deepseek-v3) |
| messages | array | Yes | メッセージ配列 |
| max_tokens | number | No | 最大トークン数 |
| temperature | number | No | サンプリング温度 (0-2) |
| stream | boolean | No | ストリーミング有効化 |

### GET /v1/chat/models

利用可能なモデル一覧を取得（認証不要）。

---

## Response Headers

| Header | Description |
|--------|-------------|
| X-AICU-Model | 使用モデル |
| X-AICU-Provider | プロバイダ (openrouter/groq/aicu/sakura) |
| X-AICU-Tokens | 消費トークン数 |
| X-AICU-AP-Cost | AP消費 |
| X-AICU-Latency-Ms | サーバーレイテンシ |

---

## Rate Limits & Costs

| Provider | Rate Limit | Cost |
|----------|------------|------|
| Groq | 30 RPM | 無料 |
| OpenRouter | プラン依存 | 2-20 AP/1K tokens |
| Sakura (kimi-k2.7-code) | さくら側無償枠 3,000 req/月 | α版は課金なし。超過・集中アクセス時は 429 を返すことがあります |

**Credits**: 15,000 AP = $1（USD 建て）

---

## Error Handling

| Code | Meaning | Action |
|------|---------|--------|
| 401 | Unauthorized / API key required | APIキー、スコープ、有効期限を確認 |
| 403 | Forbidden（スコープ不足など） | キーの `llm` スコープを確認 |
| 400 | Bad Request | パラメータ確認 |
| 429 | Rate Limited | 少し待つ |
| 500 | Server Error | リトライ |

---

## Support

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

---
*AICU Japan K.K. - 2026-08-14*