Flatkey API Quickstart: Gọi đầu tiên qua router.flatkey.ai

Nếu bạn đã dùng OpenAI SDK, con đường ngắn nhất để thực hiện cuộc gọi đầu tiên tới Flatkey API rất đơn giản: tạo một Flatkey key, trỏ client của bạn tới https://router.flatkey.ai/v1, gửi một yêu cầu chat-completions và xác nhận cuộc gọi trong console.

Hướng dẫn quickstart này sẽ đi qua toàn bộ vòng lặp đó. Nó cũng cho thấy cách thêm một chuỗi fallback cơ bản sau khi model đầu tiên hoạt động, mà không che giấu lỗi hoặc tạo ra một chuỗi retry vô hạn.

Bạn sẽ hoàn thành những gì

Đến cuối hướng dẫn này, bạn sẽ có:

1. Một tài khoản Flatkey và API key.
2. Một client tương thích OpenAI sử dụng Flatkey router.
3. Một yêu cầu thành công và một phản hồi dễ đọc.
4. Một checkpoint trong console để theo dõi usage, cost và xử lý sự cố request.
5. Một mẫu fallback nhỏ mà bạn có thể kiểm thử trước khi production.

Bạn không cần viết lại ứng dụng của mình xoay quanh một SDK mới chỉ để thực hiện smoke test này. Tài liệu công khai của Flatkey cung cấp endpoint tương thích OpenAI tại https://router.flatkey.ai/v1, vì vậy các quy trình chat, tool, streaming và structured-output phổ biến vẫn có thể giữ nguyên kiểu client quen thuộc.

Trước khi bắt đầu

Bạn cần:

• Một tài khoản Flatkey.
• Một Flatkey API key bắt đầu bằng sk-fk-.
• Python 3.9+ hoặc Node.js 18+ nếu bạn muốn dùng ví dụ SDK.
• Tên model hiện đang khả dụng cho tài khoản của bạn.

Danh mục model và tình trạng khả dụng có thể thay đổi. Hãy dùng danh mục model hiện tại hoặc console thay vì sao chép một tên model cũ vào production.

Bước 1: Tạo tài khoản Flatkey của bạn

Mở quy trình đăng ký Flatkey và tạo một tài khoản. Sau khi đăng nhập, hãy dùng console để tạo credential mà ứng dụng của bạn sẽ gửi kèm mỗi request.

Tham chiếu console

Vào Console → API Keys.

Tạo một key cho quickstart này và sao chép nó ngay lập tức. Hãy coi key như một mật khẩu: không dán nó vào mã phía client, không commit nó vào Git, không đưa nó vào ảnh chụp màn hình, và không gửi nó trong tin nhắn hỗ trợ.

Đối với môi trường nhóm, hãy tạo các key riêng cho từng developer hoặc service riêng biệt. Tài liệu của Flatkey cũng mô tả các kiểm soát theo từng key như monthly cap và tùy chọn model allowlist. Những kiểm soát này giúp dễ dàng cô lập một bài test, xoay vòng một credential, hoặc dừng một workload mà không ảnh hưởng đến mọi ứng dụng.

Đặt key trong shell của bạn:

export FLATKEY_API_KEY="sk-fk-your-key-here"

Nếu bạn dùng file .env, hãy giữ nó bên ngoài hệ thống kiểm soát phiên bản:

FLATKEY_API_KEY=sk-fk-your-key-here

Bước 2: Thay đổi base URL

Base URL tương thích OpenAI của Flatkey là:

https://router.flatkey.ai/v1

Đây là thay đổi cấu hình quan trọng nhất trong quickstart. API key của bạn xác thực request, trong khi base URL sẽ đưa request đi qua Flatkey router thay vì gửi trực tiếp đến endpoint của một nhà cung cấp khác.

Hãy giữ cả hai giá trị trong cấu hình môi trường để bạn có thể thay đổi chúng mà không cần chỉnh sửa logic ứng dụng:

export OPENAI_API_KEY="$FLATKEY_API_KEY"
export OPENAI_BASE_URL="https://router.flatkey.ai/v1"

Sử dụng các tên biến mà framework của bạn mong đợi. Một số thư viện đọc OPENAI_BASE_URL; các thư viện khác yêu cầu tùy chọn base_url hoặc baseURL khi tạo client.

Bước 3: Gửi yêu cầu đầu tiên của bạn

Bắt đầu với một prompt ngắn, có tính xác định. Mục tiêu là chứng minh xác thực, kết nối, truy cập mô hình và phân tích phản hồi trước khi thêm streaming, tools, structured output hoặc hành vi fallback.

Tùy chọn A: cURL

Thay YOUR_CURRENT_MODEL bằng một model hiện có trong danh mục Flatkey hiện tại:

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CURRENT_MODEL",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: flatkey quickstart connected"
      }
    ],
    "temperature": 0
  }'

Tùy chọn B: Python

Cài đặt OpenAI client:

pip install openai

Tạo quickstart.py:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="YOUR_CURRENT_MODEL",
    messages=[
        {
            "role": "user",
            "content": "Reply with exactly: flatkey quickstart connected",
        }
    ],
    temperature=0,
)

print(response.choices[0].message.content)
print(response.usage)

Chạy nó:

python quickstart.py

Tùy chọn C: JavaScript

Cài đặt client:

npm install openai

Tạo quickstart.mjs:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_CURRENT_MODEL",
  messages: [
    {
      role: "user",
      content: "Reply with exactly: flatkey quickstart connected",
    },
  ],
  temperature: 0,
});

console.log(response.choices[0].message.content);
console.log(response.usage);

Chạy nó:

node quickstart.mjs

Bước 4: Đọc phản hồi

Với một yêu cầu chat-completions tiêu chuẩn, hãy bắt đầu bằng bốn trường:

Một phản hồi đơn giản hóa trông như sau:

{
  "id": "chatcmpl-example",
  "model": "YOUR_CURRENT_MODEL",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "flatkey quickstart connected"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 5,
    "total_tokens": 17
  }
}

Các mã định danh và số lượng token chính xác sẽ khác nhau. Điều kiện thành công của lần gọi đầu tiên không phải là khớp từng byte; đó là một phản hồi HTTP hợp lệ, một thông điệp assistant có thể phân tích được, và thông tin usage mà ứng dụng của bạn có thể ghi nhận.

Bước 5: Kiểm tra usage sau khi gọi

Đừng dừng ở 200 OK. Một quickstart hữu ích cũng chứng minh rằng yêu cầu đã hiển thị với những người sẽ vận hành tích hợp.

Tài liệu tham chiếu Console

Mở Console → Usage & Logs sau khi gửi yêu cầu.

Tìm cuộc gọi mới và xác nhận các chi tiết có sẵn cho tài khoản của bạn, chẳng hạn như:

• Thời gian yêu cầu.
• Model hoặc route.
• Trạng thái.
• Usage token.
• Ảnh hưởng đến chi phí hoặc số dư.
• Chi tiết lỗi khi yêu cầu thất bại.

Nếu ứng dụng đã nhận được phản hồi nhưng mục log mong đợi bị thiếu, trước tiên hãy kiểm tra rằng bạn đang xem cùng một tài khoản, workspace và API key được dùng cho yêu cầu. Đồng thời ghi lại response ID và thời gian yêu cầu trước khi thử lại; hai chi tiết này giúp việc khắc phục sự cố dễ dàng hơn nhiều.

Xem lại trang giá Flatkey hiện tại trước khi chuyển từ bài kiểm tra nhanh sang khối lượng công việc ổn định. Hãy so sánh model, khối lượng yêu cầu, tổ hợp token và hành vi fallback mà bạn dự định sử dụng — không chỉ chi phí của một lần gọi thành công.

Bước 6: Thêm một chuỗi fallback an toàn

Định tuyến fallback nên được thêm sau khi model đầu tiên hoạt động. Nếu không, một route dự phòng có thể che giấu vấn đề thực sự: key không hợp lệ, base URL sai, model không khả dụng, yêu cầu sai định dạng hoặc giới hạn tài khoản.

Bắt đầu với một danh sách ngắn các model theo thứ tự mà bạn đã kiểm thử cho cùng một công việc:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

models = [
    "PRIMARY_CURRENT_MODEL",
    "FALLBACK_CURRENT_MODEL",
]

last_error = None

for model in models:
    try:
        response = client.chat.completions.create(
            model=model,
            messages=[
                {
                    "role": "user",
                    "content": "Trả về JSON với một khóa tên status và giá trị ok",
                }
            ],
            temperature=0,
        )
        print(model, response.choices[0].message.content)
        break
    except Exception as error:
        last_error = error
        print(f"Route failed: {model}")
else:
    raise RuntimeError("Tất cả các route model đã được phê duyệt đều thất bại") from last_error

Ví dụ này được cố ý giữ nhỏ. Trước khi dùng trong production, hãy thêm:

• Một danh sách hẹp các lỗi có thể thử lại.
• Thời gian chờ cho mỗi lần thử và một hạn chót tổng cho yêu cầu.
• Cơ chế backoff cho các lỗi tạm thời.
• Nhật ký có cấu trúc chứa model đã thử và ID phản hồi.
• Xác thực đầu ra cho JSON, lệnh công cụ, hoặc các schema bắt buộc khác.
• Một trần chi phí để phương án dự phòng không âm thầm chọn một tuyến không phù hợp.

Không thử lại các lỗi xác thực với nhiều model. Không thử lại các yêu cầu định dạng sai cho đến khi yêu cầu được sửa. Đừng xem mọi model là có thể thay thế cho nhau chỉ vì nó chấp nhận payload chat-completions.

Chính sách dự phòng thực tiễn

Hãy dùng bảng quyết định này làm điểm khởi đầu:

Quy tắc cốt lõi rất đơn giản: thử lại các lỗi truyền tải tạm thời; sửa các lỗi cấu hình và schema; chỉ dùng phương án dự phòng khi phương án đó đã được phê duyệt cho cùng một tác vụ sản phẩm.

Các lỗi thường gặp ở lần gọi đầu tiên

401 hoặc lỗi xác thực

Xác nhận yêu cầu dùng Authorization: Bearer <key>, key đang hoạt động, và không có khoảng trắng thừa nào bị sao chép. Kiểm tra rằng ứng dụng đang đọc biến môi trường mong đợi.

404 hoặc endpoint sai

Sử dụng base URL tương thích OpenAI https://router.flatkey.ai/v1 và đường dẫn chat /chat/completions. Tránh vô tình thêm /v1 hai lần.

Không tìm thấy model hoặc model không khả dụng

Chọn một model hiện đang khả dụng từ danh mục trực tiếp hoặc console. Đừng cho rằng tên model từ một hướng dẫn cũ vẫn còn được bật cho tài khoản của bạn.

Phản hồi HTTP thành công nhưng lỗi ứng dụng

Ghi log phản hồi thô một lần trong môi trường phát triển an toàn. Xác nhận mã của bạn đọc choices[0].message.content cho chat completions và không mong đợi schema phản hồi của một endpoint khác.

Chi tiêu bất ngờ trong lúc fallback

Ghi lại model đã thử trên mọi lần gọi, giới hạn danh sách tuyến, và xem lại Usage & Logs. Một chính sách dự phòng không có hạn chót và ranh giới chi phí có thể biến một hành động của người dùng thành nhiều yêu cầu tính phí.

Danh sách kiểm tra sản xuất

Trước khi gửi lưu lượng thực qua tích hợp, hãy xác nhận:

• [ ] Khóa API được lưu trong trình quản lý bí mật hoặc biến môi trường phía máy chủ.
• [ ] Môi trường phát triển, staging và production sử dụng các khóa riêng biệt.
• [ ] Base URL là cấu hình, không được hard-code xuyên suốt toàn bộ codebase.
• [ ] Model đã chọn khả dụng và đã được kiểm thử cho khối lượng công việc thực tế.
• [ ] Timeout, lỗi có thể thử lại và deadline tổng được xác định rõ ràng.
• [ ] Các model dự phòng sử dụng cùng một hợp đồng đầu ra bắt buộc.
• [ ] Nhật ký sử dụng và lỗi hiển thị được cho đội vận hành.
• [ ] Kỳ vọng về chi phí đã được kiểm tra so với giá hiện tại.
• [ ] Giới hạn khóa hoặc allowlist được cấu hình khi phù hợp.
• [ ] Có thể nhanh chóng khôi phục tuyến trước đó bằng một đường quay lui.

Thực hiện cuộc gọi đầu tiên, rồi tối ưu hóa

Cách nhanh nhất để đánh giá Flatkey là giữ cho bài kiểm tra đầu tiên thật hẹp. Tạo một khóa, thay đổi một base URL, gửi một yêu cầu, đọc một phản hồi, và tìm chính cuộc gọi đó trong Usage & Logs.

Sau khi luồng đó được xác minh, hãy thêm routing dự phòng như một chính sách có thể quan sát được thay vì một vòng lặp retry ẩn. Giữ danh sách model được phê duyệt ở mức ngắn gọn, bảo toàn bằng chứng lỗi, xác thực đầu ra, và xem lại bảng giá hiện tại trước khi tăng lưu lượng.

Khi bạn đã sẵn sàng, tạo một tài khoản Flatkey, thực hiện cuộc gọi đầu tiên qua router.flatkey.ai, và dùng bản ghi trên console như bài kiểm tra chấp nhận cho tích hợp của bạn.