KilgoreAI — API

Base URL & identity

Gọi tất cả endpoint theo đường dẫn tương đối của site này (ví dụ /v1/models), hoặc tuyệt đối:

• Không bắt buộc API key — server nhận diện bạn qua cookie uid, tự đặt ở yêu cầu đầu tiên. Với curl / SDK nên dùng Bearer API key ổn định (xem API keys).
• Cookie/key này quyết định quyền truy cập các cuộc trò chuyện & tệp của bạn (người khác không đọc được).

API keys (khuyên dùng cho client)

POST Bearer key giúp script/SDK của bạn có định danh ổn định — không cần cookie. Tạo mà không cần tài khoản:

curl -s -c cookie.txt /v1/auth/api-keys \
  -H "content-type: application/json" \
  -d '{"name": "my-script"}'

Phản hồi — bạn có thể sao chép lại bất cứ lúc nào trong dashboard:

{
  "id": 3,
  "key": "sk-kilg-xJ2...",
  "prefix": "sk-kilg-xJ2",
  "expires": "2026-09-25T00:00:00Z"
}

Dùng key

Gửi Authorization: Bearer <key> ở mọi endpoint /v1. Key thay thế hoàn toàn cookie uid:

curl /v1/chat/completions \
  -H "authorization: Bearer sk-kilg-..." \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5", "messages": [{"role": "user", "content": "hi"}]}

# Python (openai SDK)
from openai import OpenAI
client = OpenAI(
    base_url="v1",
    api_key="sk-kilg-...",
)
r = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "hi"}],
)
print(r.choices[0].message.content)

Mở dashboard API keys →

Models

GET/v1/models — danh sách chat + image models. GET /v1/images/models — chỉ image models.

curl -s /v1/models

Model được liệt kê theo thời gian chạy và tự cập nhật.

Chat completions

POST/v1/chat/completions — OpenAI-compatible, hỗ trợ stream: true (SSE).

curl -s /v1/chat/completions \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Giải thích SSH tunnel dễ hiểu"}
    ]
  }'

Tuỳ chọn

File đính kèm: trong user message dùng {"type": "file", "url": "..."} hoặc {"type": "file_id", "file_id": "..."} (xem Files).

Messages (Anthropic)

POST/v1/messages — giống Messages API của Anthropic (content blocks, streaming SSE).

curl -s /v1/messages \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "max_tokens": 2048,
    "system": "Trả lời bằng tiếng Việt",
    "messages": [{"role": "user", "content": "Viết đoạn thơ ngắn về lập trình viên"}]
  }'

POST/v1/messages/count_tokens — ước lượng token.

Cũng hỗ trợ incognito và include_name như chat completions.

Files

POST/v1/files — upload (multipart file), max 25MB; chấp nhận ảnh, text, PDF, Office.

curl -s /v1/files -F "file=@anh.png"

Trả về id + url. Sau đó: GET /v1/files (danh sách, kèm media_type), GET /v1/files/{id} (chi tiết), DELETE /v1/files/{id} (xoá khỏi danh sách; bản remote vẫn còn). Tệp chỉ chủ sở hữu (uid cookie) xem được; upload kèm header X-Incognito: 1 sẽ không bao giờ xuất hiện trong danh sách.

Hồ sơ

GET/v1/profile — tên hiển thị + avatar của bạn (theo cookie uid). Mặc định: {"name": "", "avatar": {"kind": "none", "preset": "", "url": ""}}.

PUT/v1/profile — cập nhật. {"name": "Nyx"} (tối đa 40 ký tự, tự trim) hoặc {"avatar": {"kind": "preset", "preset": "#4c9eea"}} (một trong các màu preset) hoặc {"avatar": {"kind": "image", "file_id": "..."}} (file bạn đã upload qua /v1/files; phải là ảnh, tối đa 2MB). Gửi {"avatar": {"kind": "none"}} để xoá avatar.

Có tên hiển thị thì mới dùng được tuỳ chọn include_name (xem Chat completions).

Chat ẩn danh

Gửi incognito: true trong body để bỏ hoàn toàn việc lưu trữ — không ghi gì vào DB và không xuất hiện trong GET /v1/conversations. Client tự gửi toàn bộ lịch sử; mỗi lượt dùng chatId mới.

Hình ảnh

POST/v1/images/generations — sinh ảnh (OpenAI-compatible).

curl -s /v1/images/generations \
  -H "content-type: application/json" \
  -d '{"model": "flux-1.1-pro", "prompt": "mèo đang code, phong cách pixel art", "n": 1, "size": "1024x1024"}'

Kết quả: data[].b64_json hoặc data[].url. Model hay dùng: flux-1.1-pro, flux-schnell, gpt-image-1, dall-e-3, imagen-4, sdxl.

Đọc văn bản

GET/v1/tts/voices — 8 giọng phổ biến + giọng tốt nhất mỗi vùng: {"popular": [...], "all": [{"locale": ..., "voice": ..., "gender": ...}]}.

POST/v1/tts — đọc văn bản, trả về audio/mpeg (kèm header X-Edge-Voice). Body: {"text": "...", "voice": "vi-VN-HoaiMyNeural", "rate": 1.0, "pitch": 1.0}. Voice không bắt buộc — tự nhận diện theo ngôn ngữ văn bản (vi/en). Text tối đa 5000 ký tự.

curl -s /v1/tts \
  -H "content-type: application/json" \
  -d '{"text": "Xin chào KilgoreAI"}' \
  -o gioi-thieu.mp3

Conversations

Mọi chat tự lưu theo cookie uid + X-Conversation-Id. Nếu không gửi conversation id, server tự cấp key mới (trả trong X-Conversation-Id response).

Góp ý & đề xuất

Trạng thái

GET/v1/health — trạng thái dịch vụ: {"status": "ok", "models": [...], "image_models": [...], "memory": {"conversations": N}}.

Giới hạn