Chat Completions dengan cURL di Berbagai Model AI

Anda dapat mempelajari lebih banyak tentang sebuah AI gateway dari satu perintah terminal daripada dari daftar fitur yang panjang. Jika gateway tersebut benar-benar kompatibel dengan OpenAI, maka permintaan curl yang sama seharusnya berfungsi di berbagai keluarga model yang didukung, sementara base URL, header otorisasi, format pesan, dan parsing respons tetap stabil.

Tutorial ini menunjukkan pola praktis dengan Flatkey: mulai dengan satu request chat-completions, pindahkan nama model ke dalam variabel, dan uji beberapa keluarga model saat ini tanpa menulis ulang integrasinya. Ini dirancang untuk developer yang ingin memvalidasi sebuah API dari terminal sebelum menambahkan SDK atau menulis kode aplikasi.

Catatan pemilihan model: Katalog model berubah. ID model di bawah ini mencerminkan dokumentasi publik Flatkey yang diperiksa pada 24 Juli 2026. Konfirmasi baris model dan ketersediaan saat ini sebelum menggunakan sebuah ID di produksi.

Request cURL chat-completions terpendek yang berfungsi

Buat kunci API Flatkey, ekspor di shell Anda, dan kirim request ke endpoint chat-completions yang kompatibel dengan OpenAI:

export FLATKEY_API_KEY="your-flatkey-api-key"

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Write a one-sentence product description for a waterproof daypack."
      }
    ]
  }'

Ada empat bagian yang penting:

Untuk model chat yang kompatibel, field utama yang Anda ganti adalah model.

Gunakan bentuk cURL yang sama di berbagai keluarga model

Letakkan ID model di variabel shell sehingga body request tidak perlu diubah:

export FLATKEY_API_KEY="your-flatkey-api-key"
export MODEL="gpt-4o-mini"

curl -sS https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL\",
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": \"Return concise ecommerce copy.\"
      },
      {
        \"role\": \"user\",
        \"content\": \"Write a product title for a lightweight waterproof daypack.\"
      }
    ],
    \"temperature\": 0.2
  }" | jq -r '.choices[0].message.content'

Sekarang jalankan ulang perintah dengan ID model terdokumentasi lainnya:

export MODEL="claude-sonnet-4-6"

export MODEL="gemini-2.5-flash"

export MODEL="deepseek-v3.1"

Permintaan ini tetap menggunakan endpoint, header, pesan, dan parser jq yang sama. Bentuk panggilan yang stabil ini adalah keunggulan operasionalnya: Anda dapat membandingkan keluarga model yang didukung tanpa harus memelihara skrip terminal terpisah untuk setiap penyedia.

Catatan pemilihan model: Bentuk permintaan yang dibagikan tidak berarti setiap model berperilaku identik. Parameter yang didukung, batas konteks, perilaku alat, perilaku keamanan, latensi, dan gaya keluaran dapat berbeda. Perlakukan kompatibilitas sebagai permukaan integrasi yang lebih sederhana, bukan sebagai bukti bahwa model-model tersebut dapat dipertukarkan.

Jalankan loop pengujian multi-model kecil

Untuk perbandingan cepat di terminal, tentukan daftar singkat dan kirim prompt yang sama ke setiap model:

#!/usr/bin/env bash
set -euo pipefail

: "${FLATKEY_API_KEY:?Set FLATKEY_API_KEY first}"

MODELS=(
  "gpt-4o-mini"
  "claude-sonnet-4-6"
  "gemini-2.5-flash"
  "deepseek-v3.1"
)

PROMPT="Write three benefit-led bullet points for a waterproof commuter backpack."

for MODEL in "${MODELS[@]}"; do
  echo
  echo "=== $MODEL ==="

  jq -n \
    --arg model "$MODEL" \
    --arg prompt "$PROMPT" \
    '{
      model: $model,
      messages: [
        {role: "system", content: "You write concise ecommerce copy."},
        {role: "user", content: $prompt}
      ],
      temperature: 0.2
    }' |
  curl -sS https://router.flatkey.ai/v1/chat/completions \
    -H "Authorization: Bearer $FLATKEY_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -r '.choices[0].message.content // .error.message'
done

Menggunakan jq -n untuk membangun JSON lebih aman daripada meng-escape string shell yang panjang secara manual. Ini juga membuat skrip lebih mudah diperluas dengan variabel, pesan tambahan, atau parameter opsional.

Simpan skrip sebagai compare-models.sh, buat dapat dieksekusi, lalu jalankan:

chmod +x compare-models.sh
./compare-models.sh

Apa yang perlu dibandingkan dalam output

Uji multi-model hanya berguna jika prompt dan metode penilaian konsisten. Untuk tugas copy ecommerce, bandingkan:

Tambahkan field timing cURL saat latensi menjadi penting:

curl -sS -o response.json \
  -w 'status=%{http_code} total=%{time_total}s\n' \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Write a five-word product tagline."}
    ]
  }'

jq . response.json

Ini memisahkan pengukuran transport dari output model. Terminal menampilkan status HTTP dan total waktu permintaan, sementara respons JSON tetap tersedia untuk diperiksa.

Catatan pemilihan model: Jangan memilih model produksi dari satu respons. Jalankan set prompt yang representatif, ulangi permintaan, dan beri skor pada output berdasarkan persyaratan yang penting bagi aplikasi Anda.

Jaga agar permintaan tetap dapat dibandingkan

Perubahan kecil pada prompt atau parameter dapat membuat pengujian model menjadi menyesatkan. Gunakan kontrol berikut:

1. Jaga messages tetap identik. Jangan memperbaiki prompt untuk satu model tetapi tidak untuk yang lain.
2. Gunakan temperature yang sama. Nilai yang lebih rendah biasanya membuat hasil perbandingan lebih mudah ditinjau.
3. Ambil JSON mentah. Simpan respons lengkap, bukan hanya teks yang dirender.
4. Catat ID model. Nama tampilan tidak cukup presisi untuk pengujian yang dapat direproduksi.
5. Pisahkan error dari jawaban yang buruk. Error transport atau ketersediaan bukan skor kualitas output.
6. Periksa ketersediaan saat ini. Model yang terdokumentasi masih dapat memiliki status operasional yang berubah.

Tambahkan penanganan kegagalan dasar

Gunakan --fail-with-body agar cURL keluar saat terjadi error HTTP sambil tetap mempertahankan body respons:

HTTP_BODY=$(mktemp)

if ! curl --fail-with-body -sS \
  -o "$HTTP_BODY" \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Return the word ready."}
    ]
  }'; then
  jq -r '.error.message // "Request failed"' "$HTTP_BODY" >&2
  rm -f "$HTTP_BODY"
  exit 1
fi

jq -r '.choices[0].message.content' "$HTTP_BODY"
rm -f "$HTTP_BODY"

Dalam kode aplikasi, tambahkan juga timeout eksplisit, retry terbatas untuk kegagalan yang dapat di-retry, dan logging yang tidak mengekspos kunci rahasia atau konten prompt sensitif.

Kebijakan pemilihan model yang praktis

Kebijakan paling sederhana adalah memilih berdasarkan beban kerja, bukan nama penyedia:

Mulailah dengan model terkecil yang secara andal melampaui ambang kualitas Anda. Tingkatkan ke model yang lebih kuat saat tugas memang membutuhkannya. Jika Anda menambahkan routing fallback, uji fallback dengan kontrak respons yang sama, bukan mengasumsikan bahwa ia dapat menggantikan model utama tanpa perubahan aplikasi.

Anda dapat meninjau akses model dan harga saat ini di Flatkey pada halaman harga sebelum memilih ID untuk pengujian produksi.

Kapan beralih dari cURL ke SDK

cURL ideal untuk mengonfirmasi empat hal dengan cepat:

• API key berfungsi
• base URL sudah benar
• model yang dipilih menerima permintaan
• bentuk respons cocok dengan parser Anda

Beralihlah ke SDK saat Anda membutuhkan helper streaming, logika retry terstruktur, respons bertipe, client yang dapat digunakan ulang, atau observabilitas di tingkat aplikasi. Simpan permintaan cURL yang berhasil dalam runbook Anda: itu tetap menjadi cara tercepat untuk memisahkan masalah akses gateway dari masalah konfigurasi SDK.

Daftar periksa implementasi akhir

• Ekspor API key alih-alih menempatkannya langsung di skrip.
• Gunakan https://router.flatkey.ai/v1 sebagai base URL.
• Kirim permintaan chat yang kompatibel ke /chat/completions.
• Pindahkan ID model ke konfigurasi.
• Bangun JSON dengan jq saat escaping shell menjadi rumit.
• Catat status HTTP, latensi, konten respons, dan data penggunaan.
• Bandingkan model dengan prompt dan parameter yang identik.
• Verifikasi ketersediaan katalog saat ini sebelum rollout produksi.
• Tambahkan timeout, retry terbatas, dan logging yang aman untuk secret di kode aplikasi.

Satu permintaan cURL yang stabil memberi Anda titik awal yang bersih. Setelah itu berfungsi, mengubah field model menjadikan permintaan tersebut sebagai harness pengujian praktis untuk beberapa keluarga model AI—tanpa harus mengubah autentikasi, base URL, atau parser respons setiap kali.

Pertanyaan yang sering diajukan

Apakah saya bisa menggunakan permintaan cURL chat-completions yang sama untuk setiap model AI?

Gunakan untuk model yang diekspos Flatkey melalui rute chat-completions yang kompatibel. Modalitas lain atau fitur spesifik protokol dapat memerlukan endpoint atau field permintaan yang berbeda.

Apa set field minimum untuk permintaan chat-completions?

Untuk permintaan dasar, sediakan model yang didukung dan array messages. Anda juga memerlukan header otorisasi bearer dan tipe konten JSON.

Mengapa nama model ditempatkan di environment variable?

Ini menjaga bentuk request tetap stabil, mengurangi kesalahan pengeditan, dan memudahkan skrip dijalankan di berbagai konfigurasi staging, evaluation, dan production.

Haruskah saya menggunakan cURL di production?

cURL sangat baik untuk verifikasi, skrip, dan runbook. Sebagian besar aplikasi production lebih diuntungkan oleh SDK atau HTTP client dengan dukungan timeout, retry, telemetry, dan penanganan tipe yang eksplisit.

Bagaimana cara memilih di antara model GPT, Claude, Gemini, dan DeepSeek?

Pilih dengan set evaluasi yang representatif. Bandingkan kepatuhan terhadap instruksi, kualitas output, latensi, penggunaan token, perilaku error, dan fitur spesifik yang dibutuhkan workload Anda. Konfirmasikan ketersediaan saat ini sebelum deployment.