Flatkey API Quickstart: Membuat Panggilan Pertama Anda Melalui router.flatkey.ai

Jika Anda sudah menggunakan SDK OpenAI, jalur tercepat untuk melakukan panggilan pertama ke Flatkey API cukup sederhana: buat kunci Flatkey, arahkan klien Anda ke https://router.flatkey.ai/v1, kirim satu permintaan chat-completions, dan konfirmasi panggilan tersebut di konsol.

Quickstart ini memandu Anda melalui seluruh alur tersebut. Ini juga menunjukkan cara menambahkan urutan fallback dasar setelah model pertama bekerja, tanpa menyembunyikan error atau membuat rantai retry yang tak terbatas.

Apa yang akan Anda selesaikan

Di akhir panduan ini, Anda akan memiliki:

1. Akun Flatkey dan API key.
2. Klien yang kompatibel dengan OpenAI menggunakan router Flatkey.
3. Satu permintaan yang berhasil dan respons yang dapat dibaca.
4. Titik pengecekan konsol untuk penggunaan, biaya, dan pemecahan masalah permintaan.
5. Pola fallback kecil yang bisa Anda uji sebelum produksi.

Anda tidak perlu menulis ulang aplikasi Anda di sekitar SDK baru untuk smoke test ini. Dokumentasi publik Flatkey mengekspos endpoint yang kompatibel dengan OpenAI di https://router.flatkey.ai/v1, sehingga workflow chat, tool, streaming, dan structured output yang umum dapat tetap menggunakan bentuk klien yang familiar.

Sebelum Anda mulai

Anda memerlukan:

• Akun Flatkey.
• API key Flatkey yang diawali dengan sk-fk-.
• Python 3.9+ atau Node.js 18+ jika Anda ingin menggunakan contoh SDK.
• Nama model yang saat ini tersedia untuk akun Anda.

Katalog model dan ketersediaan dapat berubah. Gunakan katalog model terbaru atau konsol, bukan menyalin nama model lama ke produksi.

Langkah 1: Buat akun Flatkey Anda

Buka alur pendaftaran Flatkey dan buat akun. Setelah masuk, gunakan konsol untuk membuat kredensial yang akan dikirim aplikasi Anda dengan setiap permintaan.

Referensi konsol

Buka Console → API Keys.

Buat key untuk quickstart ini dan salin segera. Perlakukan key seperti kata sandi: jangan tempelkan ke kode sisi klien, jangan commit ke Git, jangan sertakan dalam screenshot, dan jangan kirim dalam pesan dukungan.

Untuk lingkungan tim, buat key terpisah untuk developer atau layanan yang berbeda. Dokumentasi Flatkey juga menjelaskan kontrol per-key seperti batas bulanan dan allowlist model opsional. Kontrol tersebut memudahkan untuk mengisolasi pengujian, merotasi satu kredensial, atau menghentikan satu workload tanpa memengaruhi setiap aplikasi.

Setel key di shell Anda:

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

Jika Anda menggunakan file .env, simpan di luar version control:

FLATKEY_API_KEY=sk-fk-your-key-here

Langkah 2: Ubah base URL

Base URL Flatkey yang kompatibel dengan OpenAI adalah:

https://router.flatkey.ai/v1

Ini adalah perubahan konfigurasi terpenting dalam quickstart. API key Anda mengautentikasi permintaan, sementara base URL mengarahkannya melalui router Flatkey, bukan langsung ke endpoint penyedia lain.

Simpan kedua nilai dalam konfigurasi lingkungan agar Anda dapat mengubahnya tanpa mengedit logika aplikasi:

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

Gunakan nama variabel yang diharapkan oleh framework Anda. Beberapa library membaca OPENAI_BASE_URL; yang lain memerlukan opsi base_url atau baseURL saat client dibuat.

Langkah 3: Kirim permintaan pertama Anda

Mulailah dengan satu prompt yang singkat dan deterministik. Tujuannya adalah membuktikan autentikasi, konektivitas, akses model, dan parsing respons sebelum menambahkan streaming, tools, output terstruktur, atau perilaku fallback.

Opsi A: cURL

Ganti YOUR_CURRENT_MODEL dengan model yang tersedia di katalog Flatkey saat ini:

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": "Balas dengan tepat: flatkey quickstart connected"
      }
    ],
    "temperature": 0
  }'

Opsi B: Python

Instal klien OpenAI:

pip install openai

Buat 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": "Balas dengan tepat: flatkey quickstart connected",
        }
    ],
    temperature=0,
)

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

Jalankan:

python quickstart.py

Opsi C: JavaScript

Instal klien:

npm install openai

Buat 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: "Balas dengan tepat: flatkey quickstart connected",
    },
  ],
  temperature: 0,
});

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

Jalankan:

node quickstart.mjs

Langkah 4: Baca responsnya

Untuk permintaan chat-completions standar, mulailah dengan empat field:

Respons yang disederhanakan terlihat seperti ini:

{
  "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
  }
}

Pengidentifikasi yang tepat dan jumlah token akan berbeda. Kondisi sukses panggilan pertama Anda bukan kecocokan byte-for-byte; melainkan respons HTTP yang valid, pesan asisten yang dapat di-parse, dan informasi penggunaan yang dapat dicatat oleh aplikasi Anda.

Langkah 5: Periksa penggunaan setelah panggilan

Jangan berhenti di 200 OK. Quickstart yang berguna juga membuktikan bahwa permintaan terlihat oleh orang-orang yang akan mengoperasikan integrasinya.

Referensi Console

Buka Console → Usage & Logs setelah permintaan.

Cari panggilan baru dan konfirmasi detail yang tersedia untuk akun Anda, seperti:

• Waktu permintaan.
• Model atau route.
• Status.
• Penggunaan token.
• Dampak biaya atau saldo.
• Detail error saat permintaan gagal.

Jika aplikasi menerima respons tetapi entri log yang diharapkan tidak ada, pertama-tama periksa bahwa Anda sedang melihat akun, workspace, dan API key yang sama dengan yang digunakan oleh permintaan. Juga catat response ID dan waktu permintaan sebelum mencoba lagi; dua detail itu membuat pemecahan masalah jauh lebih mudah.

Tinjau halaman harga Flatkey saat ini sebelum beralih dari smoke test ke beban kerja yang berkelanjutan. Bandingkan model, volume permintaan, campuran token, dan perilaku fallback yang Anda harapkan untuk digunakan—bukan hanya biaya dari satu panggilan yang berhasil.

Langkah 6: Tambahkan urutan fallback yang aman

Routing fallback sebaiknya dilakukan setelah model pertama berfungsi. Jika tidak, route cadangan dapat menyembunyikan masalah sebenarnya: key tidak valid, base URL salah, model tidak tersedia, permintaan tidak sesuai format, atau batas akun.

Mulailah dengan daftar pendek model berurutan yang telah Anda uji untuk tugas yang sama:

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": "Return JSON with one key named status and value 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("All approved model routes failed") from last_error

Contoh ini sengaja dibuat kecil. Sebelum menggunakannya di produksi, tambahkan:

• Daftar sempit untuk error yang dapat di-retry.
• Timeout per percobaan dan tenggat waktu permintaan total.
• Backoff untuk kegagalan sementara.
• Log terstruktur yang memuat model yang dicoba dan ID respons.
• Validasi output untuk JSON, panggilan alat, atau skema wajib lainnya.
• Batas biaya agar fallback tidak diam-diam memilih rute yang tidak sesuai.

Jangan retry error autentikasi dengan beberapa model. Jangan retry permintaan yang salah format sampai permintaannya diperbaiki. Jangan menganggap semua model dapat dipertukarkan hanya karena mereka menerima payload chat-completions.

Kebijakan fallback yang praktis

Gunakan tabel keputusan ini sebagai titik awal:

Aturan intinya sederhana: retry kegagalan transport yang sementara; perbaiki kegagalan konfigurasi dan skema; gunakan fallback hanya ketika fallback tersebut disetujui untuk job produk yang sama.

Error umum saat panggilan pertama

401 atau kegagalan autentikasi

Pastikan permintaan menggunakan Authorization: Bearer <key>, key masih aktif, dan tidak ada spasi tambahan yang ikut tersalin. Verifikasi bahwa aplikasi membaca variabel environment yang diharapkan.

404 atau endpoint yang salah

Gunakan base URL yang kompatibel dengan OpenAI https://router.flatkey.ai/v1 dan path chat /chat/completions. Hindari menambahkan /v1 dua kali tanpa sengaja.

Model tidak ditemukan atau tidak tersedia

Pilih model yang saat ini tersedia dari katalog live atau konsol. Jangan mengasumsikan nama model dari tutorial lama masih diaktifkan untuk akun Anda.

Respons HTTP berhasil tetapi error aplikasi

Catat respons mentah sekali di lingkungan pengembangan yang aman. Pastikan kode Anda membaca choices[0].message.content untuk chat completions dan tidak mengharapkan skema respons dari endpoint lain.

Pengeluaran tak terduga saat fallback

Catat model yang dicoba pada setiap panggilan, batasi daftar rute, dan tinjau Usage & Logs. Kebijakan fallback tanpa tenggat waktu dan batas biaya dapat mengubah satu tindakan pengguna menjadi beberapa permintaan yang dikenakan biaya.

Daftar periksa produksi

Sebelum mengirim trafik nyata melalui integrasi, pastikan:

• [ ] Kunci API disimpan di secret manager atau environment sisi server.
• [ ] Development, staging, dan production menggunakan kunci yang terpisah.
• [ ] Base URL adalah konfigurasi, bukan di-hardcode di seluruh codebase.
• [ ] Model yang dipilih tersedia dan telah diuji untuk beban kerja yang sebenarnya.
• [ ] Timeout, error yang dapat di-retry, dan deadline total dinyatakan secara eksplisit.
• [ ] Model fallback menggunakan kontrak output yang sama dan wajib.
• [ ] Log penggunaan dan error terlihat oleh tim operasional.
• [ ] Ekspektasi biaya telah dicek terhadap harga terkini.
• [ ] Batas kunci atau allowlist dikonfigurasi jika sesuai.
• [ ] Jalur rollback dapat memulihkan route sebelumnya dengan cepat.

Lakukan panggilan pertama, lalu optimalkan

Cara tercepat untuk mengevaluasi Flatkey adalah menjaga pengujian pertama tetap sempit. Buat satu kunci, ubah satu base URL, kirim satu permintaan, baca satu respons, dan temukan panggilan yang sama di Usage & Logs.

Setelah jalur itu terbukti, tambahkan fallback routing sebagai kebijakan yang dapat diamati, bukan loop retry tersembunyi. Jaga daftar model yang disetujui tetap singkat, simpan bukti error, validasi output, dan tinjau pricing terkini sebelum meningkatkan traffic.

Ketika Anda siap, buat akun Flatkey, lakukan panggilan pertama melalui router.flatkey.ai, dan gunakan catatan di console sebagai tes penerimaan untuk integrasi Anda.