Một API. Nhiều mô hình AI.
Luôn có câu trả lời.

Quy ước chung

Danh sách endpoint

Đường dẫn /v1/… khác (ví dụ /v1/tasks, /v1/workspaces) đang trong kế hoạch và trả 501 not_implemented — nghĩa là “chưa mở”, không phải “sai URL”.

Nhóm năng lực

Bạn gọi theo tên nhóm, không theo tên mô hình. Gateway chọn mô hình trong nhóm, tự chuyển sang mô hình kế tiếp khi một mô hình lỗi hoặc hết hạn mức. Danh sách mô hình phía sau thay đổi theo thời gian — code của bạn không cần đổi. Key dùng thử được cấp một số nhóm; GET /v1/models cho biết chính xác nhóm nào bạn dùng được.

Ghim một mô hình (không khuyến khích): gửi id mô hình lấy từ GET /v1/models (dạng có dấu /) vào model (chat) hoặc pin_model (text, ảnh). Khi ghim, gateway không chuyển sang mô hình khác nếu mô hình đó lỗi (header X-FLA-Warning: pinned_model_no_t1_failover).

POST/v1/chat/completions

Tương thích OpenAI Chat Completions: dùng nguyên SDK OpenAI, chỉ đổi base_url và api_key.

Tham số

Trường lạ bị bỏ qua (không lỗi).

curl https://llm.allin1site.com/v1/chat/completions \
  -H "Authorization: Bearer fla_prod_..." \
  -H "Content-Type: application/json" \
  -H "X-FLA-Deadline-Ms: 90000" \
  -d '{
    "model": "text-quality",
    "messages": [
      {"role": "system", "content": "Bạn là nhà thơ."},
      {"role": "user", "content": "Viết bốn câu lục bát về Hà Nội"}
    ],
    "max_tokens": 1024,
    "reasoning_effort": "low"
  }'

# Phản hồi 200
{
  "id": "chatcmpl-trc_9f2c…",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "<model-id>",
  "choices": [
    {"index": 0,
     "message": {"role": "assistant", "content": "…"},
     "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 31, "completion_tokens": 120, "total_tokens": 151},
  "x_fla": {"trace_id": "trc_9f2c…", "attempts": 1, "failover_depth": 0,
            "provider": "<provider>", "model_group": "text-quality"}
}

# Python — SDK OpenAI (pip install openai)
from openai import OpenAI

client = OpenAI(base_url="https://llm.allin1site.com/v1", api_key="fla_prod_...",
                timeout=95)                      # >= deadline + 5 s
r = client.chat.completions.create(
    model="text-quality",
    messages=[{"role": "user", "content": "Tóm tắt bài sau trong 3 ý: ..."}],
    max_tokens=800,
    extra_headers={"X-FLA-Deadline-Ms": "90000"},
)
print(r.choices[0].message.content)

# Stream — chữ hiện dần, chữ đầu thường sau 1–3 giây
for chunk in client.chat.completions.create(
        model="text-quality", stream=True,
        messages=[{"role": "user", "content": "Đếm từ 1 đến 5"}],
        extra_headers={"X-FLA-Deadline-Ms": "90000"}):
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Stream và chuyển mô hình: hệ vẫn tự thử mô hình / key khác cho tới khi có chữ đầu tiên; lỗi trước mốc đó trả mã HTTP như thường (503, 429…). Sau chữ đầu tiên thì không đổi mô hình được nữa — nếu bên sinh ngắt giữa chừng, luồng kết thúc bằng data: {"error": {"code": "upstream_failed_midstream", "tokens_emitted": …}} rồi data: [DONE] (SDK OpenAI báo lỗi APIError): câu trả lời chưa đủ, gửi lại request.

// Node.js — SDK OpenAI (npm i openai)
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://llm.allin1site.com/v1",
                            apiKey: "fla_prod_...", timeout: 95_000 });
const r = await client.chat.completions.create(
  { model: "text-fast", messages: [{ role: "user", content: "Xin chào" }] },
  { headers: { "X-FLA-Deadline-Ms": "60000" } },
);
console.log(r.choices[0].message.content);

POST/v1/generate/text

Dạng gọn của ModelRelay: gửi một prompt hoặc một mảng messages (đúng một trong hai), nhận về text.

Tham số

curl https://llm.allin1site.com/v1/generate/text \
  -H "Authorization: Bearer fla_prod_..." -H "Content-Type: application/json" \
  -d '{"model_group": "review-fast", "temperature": 0,
       "prompt": "Phân loại tiêu đề sau vào một trong: the-thao, kinh-te, giai-tri. Chỉ trả JSON {\"loai\": ...}. Tiêu đề: ..."}'

# Phản hồi 200
{
  "text": "{\"loai\": \"the-thao\"}",
  "model": "<model-id>",
  "provider": "<provider>",
  "usage": {"prompt_tokens": 52, "completion_tokens": 9, "total_tokens": 61},
  "trace_id": "trc_1a7b…",
  "attempts": 1,
  "finish_reason": "stop"
}

finish_reason: "length" nghĩa là câu trả lời bị cắt vì chạm max_tokens — tăng max_tokens hoặc chia nhỏ yêu cầu.

POST/v1/generate/image

Sinh ảnh từ mô tả. Mặc định 1 ảnh; ảnh trả về dạng base64 (máy chủ không lưu ảnh, nên không có URL).

Tham số

curl https://llm.allin1site.com/v1/generate/image \
  -H "Authorization: Bearer fla_prod_..." -H "Content-Type: application/json" \
  -H "X-FLA-Deadline-Ms: 90000" \
  -d '{"prompt": "a cozy coffee shop in Hanoi old quarter, rainy evening, watercolor", "n": 1}'

# Phản hồi 200
{
  "images": [{"b64": "iVBORw0KGgo…", "mime": "image/png", "model": "<model-id>"}],
  "trace_id": "trc_77d0…",
  "attempts": 1,
  "model_group": "image-free",
  "requested": 1,
  "returned": 1,
  "missing": 0,
  "cost_usd": "0.000000"
}

Xin nhiều ảnh mà chỉ sinh được một phần ⇒ vẫn 200, returned < requested và header X-FLA-Partial: 1/3. Mô tả bị bên sinh ảnh chặn vì nội dung ⇒ 451 content_filtered — sửa mô tả, đừng gửi lại y nguyên.

# Python — lưu ảnh ra file
import base64, requests

r = requests.post("https://llm.allin1site.com/v1/generate/image",
                  headers={"Authorization": "Bearer fla_prod_...", "X-FLA-Deadline-Ms": "90000"},
                  json={"prompt": "a red lotus on a calm pond, morning light"}, timeout=95)
r.raise_for_status()
for i, img in enumerate(r.json()["images"]):
    open(f"anh_{i}.png", "wb").write(base64.b64decode(img["b64"]))

POST/v1/images/generations

Cùng chức năng với /v1/generate/image, theo dạng OpenAI Images API. Nhận prompt, n, model (tên nhóm, hoặc id có / để ghim), seed, response_format (chỉ b64_json; url ⇒ 422). Trường khác của OpenAI (size, quality…) bị bỏ qua.

# Python — SDK OpenAI
import base64
from openai import OpenAI

client = OpenAI(base_url="https://llm.allin1site.com/v1", api_key="fla_prod_...", timeout=95)
r = client.images.generate(model="image-free", prompt="isometric tiny house, pastel colors",
                           response_format="b64_json")
open("anh.png", "wb").write(base64.b64decode(r.data[0].b64_json))

# Phản hồi 200
{
  "created": 1790000000,
  "data": [{"b64_json": "iVBORw0KGgo…"}],
  "x_fla": {"trace_id": "trc_…", "attempts": 1, "model_group": "image-free",
            "requested": 1, "returned": 1, "missing": 0, "cost_usd": "0.000000"}
}

POST/v1/generate/code

Gửi mục tiêu + các file liên quan, nhận về patch (unified diff) kèm kết quả kiểm tra tự động. Cần quyền code:generate — không có sẵn trong key dùng thử, liên hệ để được cấp.

Tham số

curl https://llm.allin1site.com/v1/generate/code \
  -H "Authorization: Bearer fla_prod_..." -H "Content-Type: application/json" \
  -d '{
    "goal": "Hàm divide phải báo lỗi rõ ràng khi chia cho 0",
    "language": "python",
    "files": [{"path": "calc.py", "content": "def divide(a, b):\n    return a / b\n"}]
  }'

# Phản hồi 200
{
  "status": "succeeded",
  "mode": "patch",
  "patch": "--- a/calc.py\n+++ b/calc.py\n@@ -1,2 +1,4 @@\n def divide(a, b):\n+    if b == 0:\n+        raise ValueError(\"b must not be 0\")\n     return a / b\n",
  "files_changed": ["calc.py"],
  "explanation": "…",
  "gates": {"patch_applies": true, "syntax_ok": true, "lint_ok": true, "tests": "not_run"},
  "gate_details": {…},
  "assumptions": [],
  "flags": [],
  "model": "<model-id>", "provider": "<provider>",
  "usage": {…}, "attempts": 1, "trace_id": "trc_…"
}

File chứa chuỗi giống bí mật (API key, mật khẩu, khoá riêng…) hoặc file nhạy cảm (.env, *.pem…) ⇒ 422 redaction_blocked, không gửi đi đâu cả — gỡ bí mật rồi gửi lại.

GET/v1/models

Nhóm và mô hình mà key của bạn được dùng, ngay lúc này. Mô hình đang bị loại tạm thời nằm trong excluded kèm lý do.

curl https://llm.allin1site.com/v1/models -H "Authorization: Bearer fla_prod_..."

# Phản hồi 200 (rút gọn)
{
  "object": "list",
  "data": [
    {"id": "text-fast", "object": "model", "created": 0, "owned_by": "fla", "x_fla_kind": "group",
     "context_window": 131072, "capabilities": {"tools": true, "stream": true}},
    {"id": "<model-id>", "object": "model", "created": 0, "owned_by": "<provider>",
     "x_fla_kind": "model", "context_window": 1048576, "capabilities": {"tools": false, "stream": true}}
  ],
  "groups": [
    {"name": "text-fast", "default": true, "candidates": 6, "min_context": null,
     "endpoints": ["/v1/chat/completions", "/v1/generate/text"], "max_input_chars": 100000,
     "members": ["<model-id>", "…"],
     "excluded": [{"model": "<model-id>", "reason": "…"}]}
  ],
  "models": [
    {"id": "<model-id>", "provider": "<provider>", "context_window": 1048576, "free_status": "verified_free"}
  ],
  "image_groups": [
    {"name": "image-free", "default": true, "paid": false, "candidates": 3,
     "members": ["…"], "excluded": [], "max_n": 4}
  ]
}

candidates: 0 ⇒ nhóm đó hiện không có mô hình nào dùng được; gọi vào sẽ nhận 503.

data theo khuôn OpenAI (cho nút “Test kết nối” / danh sách model của client chuẩn): tên nhóm trước (nên dùng — có tự chuyển mô hình), rồi id mô hình lẻ (ghim). Chỉ gồm thứ gọi được qua /v1/chat/completions — nhóm sinh code không có ở đây, xem groups[].endpoints. max_input_chars: trần tổng ký tự nội dung — rút gọn trước khi gửi thay vì nhận 413.

capabilities chỉ khai điều đã đo: tools = mô hình gọi được tools (nhóm: có ít nhất một mô hình như vậy), stream = stream=true ở /v1/chat/completions. Chưa đo thì không có trường (ví dụ chế độ JSON) — đừng coi vắng mặt là “không hỗ trợ”, chỉ là “chưa biết”. context_window chỉ có khi danh mục biết; với nhóm là mức thấp nhất trong các mô hình của nhóm. created luôn 0 (không có nguồn).

GET /v1/models/{id}

id là tên nhóm hoặc id mô hình (dạng có dấu /) lấy từ data[] ở trên. Trả một phần tử data[] (khuôn OpenAI). Không có hoặc key không được dùng ⇒ 404 model_not_found.

GET/v1/me

Key của bạn tự xem mình đang được dùng gì và còn bao nhiêu hạn mức — để client tự điều tiết thay vì đợi 429. Gọi /v1/me không tốn hạn mức.

curl https://llm.allin1site.com/v1/me -H "Authorization: Bearer fla_prod_..."

# Phản hồi 200 (rút gọn)
{
  "object": "fla.tenant", "tenant": "ten-doi-tac", "scopes": ["text:generate"],
  "model_groups": ["text-fast", "text-quality"], "image_groups": [],
  "limits": {"rpm": 60, "dong_thoi": 5, "token_ngay": 2000000},
  "usage":  {"rpm": 3, "dong_thoi": 0, "token_ngay": 18250},
  "reset": {"token_ngay_at": "2026-10-11T00:00:00Z", "token_ngay_in_seconds": 41120, "rpm_in_seconds": 27}
}

limits là hạn mức đang áp cho key này (mặc định hoặc mức riêng đã cấp). usage: request phút này / đang chạy cùng lúc / token hôm nay. Không đọc được bộ đếm ⇒ vẫn 200, usage là null kèm usage_unavailable (lý do) — không phải lỗi của bạn. Hạn mức token reset lúc 0 giờ UTC.

GET/healthz  GET/version

Không cần key. /healthz ⇒ {"status": "ok", "uptime_s": …} khi dịch vụ còn sống; /version ⇒ phiên bản đang chạy. Dùng cho giám sát, không tính vào hạn mức key.

curl https://llm.allin1site.com/healthz

Header

Bạn gửi

Bạn nhận

Giới hạn & hạn mức

Hạn mức key dùng thử có thể khác mặc định — cấp theo nhu cầu bạn đăng ký. Token ngày tính cả vào lẫn ra, đặt lại lúc 0h UTC (7h sáng giờ Việt Nam).

Lỗi & cách xử lý

Mọi lỗi có cùng dạng. Khi gateway đã thử gọi mô hình, attempts cho biết từng lần thử và vì sao chuyển tiếp.

{
  "error": {
    "code": "all_candidates_exhausted",
    "message": "…",
    "trace_id": "trc_…",
    "retry_after_ms": 30000,
    "attempts": [
      {"n": 1, "provider": "<provider>", "model": "<model-id>", "key": "key_1a2b3c4d",
       "error": "RATE_LIMITED", "http_status": 429, "latency_ms": 112, "reason": "…"},
      {"n": 2, "provider": "<provider>", "model": "<model-id>", "key": null,
       "error": "SKIP", "http_status": null, "latency_ms": 0, "reason": "…"}
    ]
  }
}

Khuyến nghị gọi lại: chỉ thử lại với 429 / 503, chờ đúng retry_after_ms (hoặc header Retry-After), tối đa 1 – 2 lần. Không thử lại 400 / 401 / 403 / 413 / 422 / 451 — gửi lại y nguyên sẽ cho đúng lỗi đó. Gateway đã tự chuyển mô hình bên trong; gọi lại dồn dập chỉ làm hạn mức cạn nhanh hơn.

SDK OpenAI: mặc định SDK tự thử lại 2 lần với 429 / 5xx — gặp 503 do quá tải, 2 lần đó chỉ nhân tải lên. Hãy đặt max_retries từ 0 đến 1 (Python: OpenAI(max_retries=1); Node: new OpenAI({ maxRetries: 1 })). Với các lỗi 503 shed, deadline_exceeded, all_candidates_exhausted, cost_guard_tripped gateway gửi kèm header x-should-retry: false để SDK không tự thử lại; 429 tenant_rate_limited và ip_rate_limited thì không, SDK chờ theo Retry-After là đúng.