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:

x-api-key: <key> cũng dùng được — đó là header Anthropic SDK gửi, nên key của SDK này không cần cấu hình thêm. Cùng một credential, cùng quyền; nếu có cả hai header, Authorization được ưu tiên.

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).

Responses (OpenAI)

POST/v1/responses — API mới hơn của OpenAI, dành cho client chỉ nói Responses (Agents SDK và các client tương tự). Cùng model, cùng streaming, cùng bộ nhớ hội thoại với Chat completions.

curl -s /v1/responses \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "input": "Giải thích SSH tunnel dễ hiểu"
  }'

from openai import OpenAI
client = OpenAI(
    base_url=v1,
    api_key="sk-kilg-...",
)
r = client.responses.create(
    model="claude-sonnet-5",
    input="hi",
)
print(r.output_text)

Tuỳ chọn

Response đã lưu

id của người khác trả về 404, không bao giờ lộ nội dung của họ.

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 "[email protected]"

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.

Memory & phiên làm việc

Conversation được lưu theo identity, không phải theo từng API key: mọi key tạo từ cùng một tài khoản/trình duyệt dùng chung một danh sách conversation. Nếu muốn mỗi API key có memory hoàn toàn riêng, nhờ quản trị viên bật MEMORY_SCOPE=key — khi đó conversation tạo bởi key này sẽ không nhìn thấy bởi key khác.

Một phiên chỉ nối tiếp khi dùng cùng conversation key. Hãy gửi X-Conversation-Id (hoặc trường conversation_id trong body) duy nhất cho mỗi phiên và tái dùng ở mọi lượt. Không gửi thì server tự suy key từ toàn bộ lịch sử trong request — phiên MỚI có nội dung khác sẽ luôn bắt đầu conversation mới và không bao giờ thấy ngữ cảnh của phiên cũ.

Client tự giữ lịch sử? Mọi câu trả lời đều mang header X-Conversation-Id của conversation nó rơi vào, nên client chỉ gửi tin nhắn mới mỗi lượt vẫn đọc header một lần rồi ghim lại được — nếu không, mỗi lượt lại sinh key mới và lịch sử của chính bạn không bao giờ tới được model. Nếu bạn gửi lại toàn bộ lịch sử mỗi lượt thì không cần header này.

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.

Video

GET/v1/videos/models — danh sách video model (id, label, thời lượng tối thiểu/tối đa, tỉ lệ khung hình).

POST/v1/videos/generations — đưa một job sinh video vào hàng đợi. Theo cơ chế ticket: lệnh gọi trả về ngay và bạn theo dõi trạng thái sau.

curl -s /v1/videos/generations \
  -H "content-type: application/json" \
  -d '{"model": "video-ltx-2.5", "prompt": "phối cảnh thời gian của một thành phố về đêm", "duration": 5, "aspect_ratio": "16:9"}'

Phản hồi: {"ticket": "vid_...", "model": "video-ltx-2.5", "status": "queued"}.

GET/v1/videos/status/{ticket} — hỏi trạng thái tới khi xong:

curl -s /v1/videos/status/vid_xxx

Trả về {"status": "queued|running|done|failed", "progress": 0.0-1.0, ...}. Khi xong sẽ có url (bản gốc) và media_url (đi qua proxy). Ticket không tồn tại → 404 — ticket lưu trong bộ nhớ và mất khi khởi động lại.

Đọ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. Server không trả lại key nó tự suy ra, nên muốn nối tiếp cuộc trò chuyện, client phải tự chọn id và gửi ở mọi lượt (xem Memory & phiên làm việc).

Chia sẻ

Xuất bản một bản chụp chỉ-đọc của hội thoại ở URL công khai. Link vẫn hoạt động kể cả khi bạn sửa hoặc xoá hội thoại gốc; khách xem thấy đúng bản chụp đó.

Bất kỳ ai có link cũng đọc được bản chụp — link không thể đoán và không được lập chỉ mục, nhưng hãy coi nó là công khai. Khách chỉ thấy tên hội thoại, model và các tin nhắn; họ không truy cập được hội thoại hay file khác của bạn.

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