# AICU API

> All the world's AI, on one URL. OpenAI-compatible chat, image generation (GPT-Image-2.5 / Nano Banana), character voices (ElevenLabs), transcription and X post reads behind one API key. Prepaid AP (1 USD = 10,000 AP); only HTTP 200 is billed; errors and cache hits are free.

Base URL: https://api.aicu.ai/v1 (images for the OpenAI SDK: https://api.aicu.ai/v2.5). Auth: Authorization: Bearer $AICU_API_KEY. Keys: https://api.aicu.ai/dashboard/keys
Live model list and prices (no auth): GET https://api.aicu.ai/v1/models

## Start here
- Getting started (keys, AP, error envelope, rate limits): https://api.aicu.ai/docs/api-reference
- Agent skills (plain text, one per service): https://api.aicu.ai/skills — llm, jev, tts, stt, images, x
- OpenAPI 3.1 with request/response examples: https://api.aicu.ai/openapi.json
- Docs index with explanations: https://api.aicu.ai/docs/llms.txt

## Endpoints (public)
### Health / Index
- GET https://api.aicu.ai/
- GET https://api.aicu.ai/health
- GET https://api.aicu.ai/health/stats

### Public Stats（公開統計）
- GET https://api.aicu.ai/v1/stats

### 週次のお知らせ（メールニュースの素）
- GET https://api.aicu.ai/announce_weekly.json
- GET https://api.aicu.ai/v1/announce/weekly.json

### LLM (OpenAI 互換)
- GET https://api.aicu.ai/v1/chat/models
- POST https://api.aicu.ai/v1/chat/completions (key, scope llm) — per-model AP

### Jev（TypeSafe・確率を返す）
- POST https://api.aicu.ai/v1/jev (key, scope llm) — 2 AP

### LLM モデル
- GET https://api.aicu.ai/v1/models
- GET https://api.aicu.ai/v1/models/:id
- GET https://api.aicu.ai/v1/models/popularity

### TTS / STT
- GET https://api.aicu.ai/v1/tts/voices (key)
- POST https://api.aicu.ai/v1/tts/estimate
- POST https://api.aicu.ai/v1/tts/generate (key, scope tts) — per-model AP
- POST https://api.aicu.ai/v1/tts/speech (key, scope tts) — per-model AP
- POST https://api.aicu.ai/v1/tts/transcriptions (key, scope tts) — per-model AP

### Audio（OpenAI 標準パス別名）
- GET https://api.aicu.ai/v1/audio/voices (key)
- POST https://api.aicu.ai/v1/audio/estimate
- POST https://api.aicu.ai/v1/audio/generate (key, scope tts) — per-model AP
- POST https://api.aicu.ai/v1/audio/speech (key, scope tts) — per-model AP
- POST https://api.aicu.ai/v1/audio/transcriptions (key, scope tts) — per-model AP

### TTS（ElevenLabs 互換パス）
- GET https://api.aicu.ai/v1/el/voices (key)
- POST https://api.aicu.ai/v1/el/tts (key, scope tts) — per-model AP

### Images（生成・証明・ギャラリー）
- GET https://api.aicu.ai/v1/images/beacon
- GET https://api.aicu.ai/v1/images/candidate/:id (key, scope images)
- GET https://api.aicu.ai/v1/images/cert/:id
- GET https://api.aicu.ai/v1/images/characters
- GET https://api.aicu.ai/v1/images/file/:id (key, scope images)
- GET https://api.aicu.ai/v1/images/gallery
- GET https://api.aicu.ai/v1/images/gallery/:id
- GET https://api.aicu.ai/v1/images/license/:token
- GET https://api.aicu.ai/v1/images/models
- GET https://api.aicu.ai/v1/images/recent (key, scope images)
- GET https://api.aicu.ai/v1/images/sets/:id (key, scope images)
- GET https://api.aicu.ai/v1/images/status/:id (key, scope images)
- POST https://api.aicu.ai/v1/images/:id/certify (key, scope images)
- POST https://api.aicu.ai/v1/images/characters (key, scope images)
- POST https://api.aicu.ai/v1/images/edits (key, scope images) — per-model AP
- POST https://api.aicu.ai/v1/images/generations (key, scope images) — per-model AP
- POST https://api.aicu.ai/v1/images/inspect
- POST https://api.aicu.ai/v1/images/select (key, scope images)

### 動画生成（Video）
- GET https://api.aicu.ai/v1/video/file/:id (key, scope video)
- GET https://api.aicu.ai/v1/video/status/:id (key, scope video)
- POST https://api.aicu.ai/v1/video/generate (key, scope video) — per-model AP

### Images（OpenAI 同形 /v2.5・SDK は base_url を向けるだけ）
- GET https://api.aicu.ai/v2.5/images/models
- GET https://api.aicu.ai/v2.5/models
- POST https://api.aicu.ai/v2.5/images/edits (key, scope images) — per-model AP
- POST https://api.aicu.ai/v2.5/images/generations (key, scope images) — per-model AP

### Characters
- GET https://api.aicu.ai/v1/char
- GET https://api.aicu.ai/v1/char/:id

### Services（段階: 社内企画 → 無料 → 企画 → 課金）
- GET https://api.aicu.ai/v1/services/:id

### X 読み取りゲートウェイ
- GET https://api.aicu.ai/v1/x/search (key, scope x) — 2250 AP
- GET https://api.aicu.ai/v1/x/status/:id (key, scope x) — 100 AP
- GET https://api.aicu.ai/v1/x/timeline/:username (key, scope x) — 2250 AP
- GET https://api.aicu.ai/v1/x/user/:username (key, scope x) — 100 AP
- POST https://api.aicu.ai/v1/x/verify (key, scope x) — 0 AP
- POST https://api.aicu.ai/v1/x/verify/code (key, scope x)

### Certs（AGT）
- GET https://api.aicu.ai/v1/certs (key, scope cert)
- GET https://api.aicu.ai/v1/certs/:certId
- GET https://api.aicu.ai/v1/certs/claims (key, scope cert)
- POST https://api.aicu.ai/v1/certs (key, scope cert)
- POST https://api.aicu.ai/v1/certs/:certId/approve (key, scope cert)
- POST https://api.aicu.ai/v1/certs/:certId/claim (key, scope cert)
- POST https://api.aicu.ai/v1/certs/:certId/claim/approve (key, scope cert)
- POST https://api.aicu.ai/v1/certs/:certId/claim/reject (key, scope cert)
- POST https://api.aicu.ai/v1/certs/:certId/image (key, scope cert)
- POST https://api.aicu.ai/v1/certs/:certId/revoke (key, scope cert)

### Me（利用者本人の面・X-AICU-User-Token）
- GET https://api.aicu.ai/v1/me/certs (key, scope cert)

### Royalty（支払先ダッシュボード）
- GET https://api.aicu.ai/v1/royalty/grants (key)
- GET https://api.aicu.ai/v1/royalty/summary (key)
- POST https://api.aicu.ai/v1/royalty/express-login (key)

### Billing (Stripe)
- GET https://api.aicu.ai/v1/stripe/balance (key)
- GET https://api.aicu.ai/v1/stripe/packages
- POST https://api.aicu.ai/v1/stripe/checkout (key)
- POST https://api.aicu.ai/v1/stripe/portal (key)
- POST https://api.aicu.ai/v1/stripe/subscribe (key)

### Users / Keys
- DELETE https://api.aicu.ai/v1/users/keys/:id (key)
- GET https://api.aicu.ai/v1/users/keys (key)
- GET https://api.aicu.ai/v1/users/me (key)
- GET https://api.aicu.ai/v1/users/usage (key)
- POST https://api.aicu.ai/v1/users/keys (key)
- POST https://api.aicu.ai/v1/users/login-bonus/claim (key)
- POST https://api.aicu.ai/v1/users/register

### API Keys（introspection）
- GET https://api.aicu.ai/v1/keys/self (key)

### Usage / Credits
- GET https://api.aicu.ai/v1/usage (key)
- GET https://api.aicu.ai/v1/usage/credits (key)
- GET https://api.aicu.ai/v1/usage/logs (key)
- GET https://api.aicu.ai/v1/usage/subjects (key)

## Rules of thumb
- Never hard-code the key; read it from the AICU_API_KEY environment variable.
- Errors are { "error": { "code", "message" } }; branch on code. 402 = top up AP, 403 forbidden_scope = key lacks the scope, 429 = slow down.
- Generations over 60 s are not meant to be awaited in an app: the result is emailed to the key owner (attachment). Opt out with notify_on_timeout: false.
- To stay under 60 s: quality low/medium/high at 1024x1024. See typical_latency_s_by_quality in GET /v1/images/models.
- Image generation may exceed 100 s: keep the response id and poll GET /v1/images/status/{id}.
- Video is async by design: POST /v1/video/generate returns 202 with an id; fetch it with GET /v1/video/status/{id}.
- Same input + same settings on TTS/images is a cache hit and costs nothing.

Generated from scripts/gen-api-spec.mjs (single source of truth). News and price notices: https://api.aicu.ai/news