API 使用方法

一个 REST API 密钥即可调用 LLM、图像、音频、虚拟形象和视频。语音 TTS 首个音频字节约 100ms，图像数秒，视频通过异步任务返回。

使用方法（4 步）

1. 1. 登录 / 注册
   先登录账户。若没有账户可免费注册。
2. 2. 签发 API 密钥
   在“API 管理”页面填写项目名称并点击签发。明文密钥仅在创建时显示一次 — 请复制保存（数据库只存哈希）。
3. 3. 第一个请求
   带上 Authorization: Bearer <你的密钥> 调用下面的端点。
4. 4. 处理响应 / 运维
   图像和音频返回 base64，视频返回任务 id 供轮询。可通过 timing 查看速度。吊销不用的密钥，泄露时吊销并重新签发。

延迟参考（RTX PRO Blackwell）

认证

每个请求都需将 API 密钥作为 Bearer 令牌发送。可在“API 管理”页面签发密钥（明文仅在创建时显示一次）。

Authorization: Bearer kotonia_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

对话 / LLM API（兼容 OpenAI）

兼容 OpenAI 的 chat completions 端点。只需把 OpenAI 的 Python / JS SDK 的 base_url 指向我们即可直接使用。tools / tool_choice 原样透传，因此 agent 场景也能用原生 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);

模型

提供两个模型:

• kotonia-llm-basic（= kotonia-llm）: 运行在本地 GPU 的默认模型。免费（有每日请求上限），首个 token 很快。需要推理时用 kotonia-llm-basic:think。
• kotonia-llm-standard: 云端级更高档位。按实际使用的 token 从预付余额计费（余额不足返回 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 会在末尾追加 /v1/messages，因此 base_url 应设为 /api（而非 /api/v1）。暂不支持流式，图像块不转换（以文本/工具为主）。

图像 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）。

响应码