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 https://kotonia.ai/api/v1/images/loras \
  -H "Authorization: Bearer $KOTONIA_API_KEY"

# → { "model": "hidream-o1-image", "loras": [ { "name": "kotonia03", "requires_paid": false } ] }
# Use a returned name in /images/generations:
# "loras": [ { "name": "kotonia03", "weight": 0.75 } ]

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，编辑模式）、loras（[{name, weight}]，支持叠加）。GET /images/loras 返回已加载的 name 和 requires_paid（image 作用域）。weight 为 0〜2，默认 1。也支持 lora / lora_weight 单个指定，loras 优先。参考图像编辑也可使用。限制: prompt 不超过 4000 字、size 每边 256〜2048（超出返回 400）。

音频 API

curl "https://kotonia.ai/api/v1/audio/voices?engine=voxcpm" \
  -H "Authorization: Bearer $KOTONIA_API_KEY"

# → { "engine": "voxcpm", "voices": [
#     { "ref_id": "...", "label": "...", "description": "...", "native_lang": "en",
#       "visibility": "official", "mine": false }
#   ] }
# Use the same engine and a returned ref_id in /audio/speech or /audio/generations:
# "engine": "voxcpm", "ref_id": "<ref_id from list>"
# For Irodori references, list with ?engine=irodori instead.

流式语音合成（推荐）

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": "voxcpm",
    "language": "en"
  }' \
  --output speech.frames

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

engine: voxcpm（默认、多语言）/ irodori / voicevox。可选: voice, speed, instruct, ref_id, seed。voxcpm 中 voice 为声音设计描述。GET /audio/voices?engine=voxcpm（或 irodori）返回官方、公开及自己的参考声音（audio 作用域，默认 voxcpm）。使用相同 engine 和返回的 ref_id，可在流式及批处理合成中固定声音。此列表不包含 VOICEVOX 说话人。限制: 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": "voxcpm",
    "language": "en"
  }'

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

语音识别（STT）

curl -X POST https://kotonia.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $KOTONIA_API_KEY" \
  -F "file=@speech.wav"

# → { "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": "voxcpm", "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）。

响应码