API の使い方

LLM・画像・音声・アバター・動画を1本のAPIキーで呼べる REST API です。音声 TTS は最初の音声バイトまで ~100ms、画像は数秒、動画は非同期ジョブで返します。

使い方（4 ステップ）

1. 1. ログイン / 新規登録
   まずアカウントにログインします。未登録なら無料で登録できます。
2. 2. APIキーを発行
   「API管理」ページでプロジェクト名を入れて「発行」。平文キーは発行直後の 1 回だけ表示されるので安全な場所にコピーしてください（DB にはハッシュのみ保存）。
3. 3. 最初のリクエスト
   Authorization: Bearer <あなたのキー> を付けて下記のエンドポイントを呼びます。
4. 4. レスポンス処理 / 運用
   画像・音声は base64、動画はジョブ ID を受け取りポーリング。各レスポンスの timing で速度を確認できます。不要なキーは失効、漏洩時は失効して再発行します。

レイテンシ目安（RTX PRO Blackwell）

認証

すべてのリクエストに APIキーを Bearer トークンとして付けます。キーは「API管理」ページから発行します（平文は発行直後の1回だけ表示）。

Authorization: Bearer kotonia_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

チャット / LLM API（OpenAI 互換）

OpenAI 互換の chat completions エンドポイントです。base_url を差し替えるだけで OpenAI の Python / JS SDK からそのまま使えます。tools / tool_choice はそのまま透過するので、エージェント用途でもネイティブ tool calling が効きます。

curl -X POST https://kotonia.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $KOTONIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kotonia-llm-basic",
    "messages": [ { "role": "user", "content": "Hello!" } ]
  }'

# → OpenAI-shaped: { "choices": [ { "message": { "content": "..." } } ],
#     "usage": { ... }, "timing": { "total_ms": 480 } }

OpenAI SDK で使う（base_url を差し替えるだけ）

from openai import OpenAI

client = OpenAI(
    base_url="https://kotonia.ai/api/v1",
    api_key="YOUR_KOTONIA_API_KEY",   # kotonia_...
)

resp = client.chat.completions.create(
    model="kotonia-llm-basic",        # free (local) · or "kotonia-llm-standard" (metered)
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://kotonia.ai/api/v1",
  apiKey: process.env.KOTONIA_API_KEY,   // kotonia_...
});

const resp = await client.chat.completions.create({
  model: "kotonia-llm-basic",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(resp.choices[0].message.content);

モデル

2 つのモデルを提供しています:

• kotonia-llm-basic（= kotonia-llm）: ローカル GPU で動く既定モデル。無料（日次リクエスト上限あり）、初回トークンが速い。reasoning を使いたいときは kotonia-llm-basic:think を指定。
• kotonia-llm-standard: クラウド級の上位モデル。実際に使ったトークン量に応じてプリペイド残高から従量課金されます（残高不足時は 402 を返すので basic に切替可）。

注: 現時点で stream:true は非対応（内部で非ストリーミングにフォールバック）。max_tokens は上限あり。レスポンスの timing で速度を確認できます。

Anthropic 互換 (/messages)

Anthropic Messages API 互換の /messages も用意しています。Anthropic の公式 SDK や Claude Code から base_url を差し替えるだけで利用できます（同じ kotonia_ キーを x-api-key として送信）。tools / tool_result も内部で OpenAI 形式へ変換して透過します。

curl -X POST https://kotonia.ai/api/v1/messages \
  -H "x-api-key: $KOTONIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kotonia-llm-basic",
    "max_tokens": 256,
    "messages": [ { "role": "user", "content": "Hello!" } ]
  }'

# → { "type": "message", "content": [ { "type": "text", "text": "..." } ],
#     "stop_reason": "end_turn", "usage": { "input_tokens": N, "output_tokens": M } }

from anthropic import Anthropic

client = Anthropic(
    base_url="https://kotonia.ai/api",          # the SDK appends /v1/messages
    api_key="YOUR_KOTONIA_API_KEY",  # kotonia_... (sent as x-api-key)
)

msg = client.messages.create(
    model="kotonia-llm-basic",       # or "kotonia-llm-standard" (metered)
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(msg.content[0].text)

注: SDK の base_url は末尾に /v1/messages が付くため /api（/api/v1 ではない）を指定します。stream は未対応、画像ブロックは未変換（テキスト/ツール中心）。

画像 API

curl -X POST https://kotonia.ai/api/v1/images/generations \
  -H "Authorization: Bearer $KOTONIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a serene japanese garden at dawn, soft light",
    "size": "1024x1024",
    "steps": 20
  }'

# → { "data": [ { "b64_json": "<PNG base64>" } ], "timing": { "total_ms": 4200 } }

任意: seed, guidance_scale, shift, ref_image（base64、編集モード）。制限: prompt 4000 文字以内、size は各辺 256〜2048（範囲外は 400）。

音声 API

ストリーミング音声合成（推奨）

curl -X POST https://kotonia.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $KOTONIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello, what a lovely day.",
    "engine": "qwen3",
    "language": "en",
    "split_mixed_languages": false
  }' \
  --output speech.frames

# Binary stream: repeated [4-byte big-endian WAV length][WAV bytes]

engine: qwen3（既定・多言語）/ irodori / voicevox。任意: voice, speed, instruct, split_mixed_languages。制限: input 4000 文字以内。ストリームは長さ付き WAV フレームです。

base64 音声合成（バッチ用途）

curl -X POST https://kotonia.ai/api/v1/audio/generations \
  -H "Authorization: Bearer $KOTONIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello, what a lovely day.",
    "engine": "qwen3",
    "language": "en"
  }'

# → { "audio": { "b64": "<WAV base64>", "format": "wav", "sample_rate": 24000 },
#     "timing": { "first_byte_ms": 92, "total_ms": 480 } }

音声認識（STT）

curl -X POST https://kotonia.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $KOTONIA_API_KEY" \
  -F "[email protected]"

# → { "text": "...", "timing": { "stt_api_ms": 320, "total_server_ms": 325 } }

multipart/form-data の file を送信します。アップロード上限は 25MB です。

アバター API

# List prepared avatars
curl https://kotonia.ai/api/v1/avatars \
  -H "Authorization: Bearer $KOTONIA_API_KEY"

# Stream speech plus avatar frames
curl -X POST https://kotonia.ai/api/v1/avatars/my-avatar/speech \
  -H "Authorization: Bearer $KOTONIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": "Hello!", "tts_backend": "qwen3", "language": "en", "fps": 25 }' \
  --output avatar.stream

# Binary stream: repeated [1-byte type][4-byte big-endian length][payload]
# type 0 = WAV audio, type 1 = JPEG video frame

GET /avatars と発話は avatar スコープ、POST/DELETE は管理者発行の avatar:write スコープが必要です。発話ストリームは type 0 が WAV、type 1 が JPEG フレームです。

動画 API（非同期）

# 1) submit job
curl -X POST https://kotonia.ai/api/v1/videos/generations \
  -H "Authorization: Bearer $KOTONIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "a cat walking through neon-lit streets", "width": 768, "height": 512 }'

# → { "id": "<job_id>", "status": "queued", "poll_url": "/api/v1/videos/generations/<job_id>" }

# 2) poll
curl https://kotonia.ai/api/v1/videos/generations/<job_id> \
  -H "Authorization: Bearer $KOTONIA_API_KEY"

# → { "status": "completed", "data": [ { "url": "/api/ltx/video?path=..." } ] }

任意: image（base64、I2V）、audio（base64、A2V リップシンク）、num_frames。制限: prompt 4000 文字以内、width/height は各辺 256〜1280、num_frames は 200 以下（範囲外は 400）。

レスポンスコード