API 使用方法

在本地 GPU 上生成图像、音频和视频的 REST API。一个 API 密钥即可调用，请求格式兼容 OpenAI。语音 TTS 首个音频字节约 100ms，图像数秒，视频通过异步任务返回。每个响应都带 timing 字段，速度可实测验证。

使用方法（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

图像 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/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 } }

engine: qwen3（默认，多语言）/ irodori / voicevox。可选: voice, speed, instruct。限制: input 不超过 4000 字。

视频 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）。

响应码