Dokumentasi

Tiga langkah: daftar dengan Gmail, buat API key di dasbor, lalu kirim permintaan pertama. Kunci ditampilkan sekali saat dibuat — setelah itu hanya awalannya yang bisa dilihat lagi, karena yang kami simpan adalah hash-nya.

curl https://v1.freeapikey.site/v1/chat/completions \
  -H "Authorization: Bearer $FREEAPIKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "MODEL_ID",
        "messages": [
          { "role": "user", "content": "Halo, apa kabar?" }
        ]
      }'

Ganti MODEL_ID dengan salah satu id di tabel Model. Simpan kunci di variabel lingkungan, jangan di dalam kode yang ikut ter-commit, dan jangan pernah mengirimkannya ke peramban.

Setiap permintaan ke gateway membawa API key di header Authorization. Kunci selalu berawalan fak_.

Authorization: Bearer fak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Skema Bearer adalah bentuk yang dikirim SDK OpenAI dan yang sebaiknya kamu pakai. Gateway juga menerima kunci tanpa skema, semata karena sebagian klien HTTP menghilangkannya.

Gateway tidak pernah membaca cookie: identitas permintaan sepenuhnya berasal dari header ini. Kunci yang salah, kunci yang sudah dicabut, dan akun yang ditangguhkan dibedakan menjadi tiga kode error tersendiri — lihat Kode error.

https://v1.freeapikey.site/v1

Base URL sudah memuat /v1. Menambahkannya sekali lagi di jalur permintaan menghasilkan /v1/v1/… dan NOT_FOUND — kekeliruan yang paling sering terlihat seperti gangguan layanan padahal bukan.

Endpoint yang tersedia:

• POST /chat/completions — chat completion, dengan atau tanpa streaming.
• GET /models — daftar model yang bisa dirutekan. Butuh API key, sama seperti endpoint lain.

Belum ada endpoint lain. Bila kamu membutuhkan sesuatu yang tidak ada di daftar ini, ia memang belum ada — bukan sedang bermasalah.

Daftar berikut diambil langsung dari katalog gateway saat halaman ini dibuka, jadi ia mengikuti registry tanpa menunggu rilis situs.

Mengambil daftar dari kode

curl https://v1.freeapikey.site/v1/models \
  -H "Authorization: Bearer $FREEAPIKEY_API_KEY"

Body berupa JSON. model dan messages wajib; sisanya opsional.

{
  "model": "MODEL_ID",
  "messages": [
    { "role": "system", "content": "Jawab ringkas dalam bahasa Indonesia." },
    { "role": "user", "content": "Halo, apa kabar?" }
  ],
  "stream": false,
  "max_tokens": 512,
  "temperature": 0.7,
  "top_p": 1,
  "n": 1
}

Field yang divalidasi gateway: model, messages, stream, stream_options, max_tokens, max_completion_tokens, temperature (0–2), top_p (0–1), n (1–8), dan tools. Field lain diteruskan apa adanya ke penyedia di hulu, sehingga parameter khusus penyedia tetap bisa dipakai — tapi gateway tidak menjanjikan apa pun tentangnya.

Peran yang diterima pada messages: system, user, assistant, tool, dan developer. Isi pesan boleh berupa string atau larik content-part multimodal.

Body dibatasi 2 MB. Melebihi itu dijawab PAYLOAD_TOO_LARGE sebelum apa pun diproses.

Respons sukses diteruskan dari penyedia di hulu dalam bentuk OpenAI. Yang gateway ubah hanya headernya: header yang bisa mengungkap identitas pemasok dibuang, dan x-request-id milik kami ditambahkan.

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1770000000,
  "model": "MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Halo! Ada yang bisa dibantu?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 9, "total_tokens": 21 }
}

Bentuk error

Di gateway (https://v1.freeapikey.site/v1), error memakai amplop OpenAI, sehingga SDK resmi memunculkannya secara alami. Cabangkan logika pada error.code, bukan pada teks pesannya.

{
  "error": {
    "message": "Daily token quota exceeded. Quota resets at 00:00 UTC.",
    "type": "insufficient_quota",
    "code": "QUOTA_EXCEEDED",
    "request_id": "8f2c1a4b-5d6e-4f70-91a2-c3d4e5f60718"
  }
}

Endpoint platform (dasbor, referral, tagihan) memakai amplop yang berbeda. Kode error-nya berasal dari registry yang sama.

{
  "success": false,
  "error": {
    "code": "TOO_MANY_ATTEMPTS",
    "message": "Too many attempts. Please try again later.",
    "requestId": "8f2c1a4b-5d6e-4f70-91a2-c3d4e5f60718"
  }
}

Setiap respons membawa header x-request-id. Sertakan nilainya saat melapor: itu yang membuat permintaanmu bisa dicari di log kami.

Kirim stream: true untuk menerima server-sent events. Byte-nya diteruskan tanpa dibuffer, jadi token pertama sampai secepat penyedia di hulu mengirimnya.

curl -N https://v1.freeapikey.site/v1/chat/completions \
  -H "Authorization: Bearer $FREEAPIKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "MODEL_ID",
        "messages": [{ "role": "user", "content": "Tulis pantun singkat." }],
        "stream": true
      }'

Frame penutup membawa hitungan token

Gateway selalu menyalakan stream_options.include_usage — juga bila kamu mengirimnya sebagai false. Akuntansi token bukan keputusan klien, dan tanpa itu setiap permintaan streaming akan tercatat sebagai perkiraan. Efek sampingnya menguntungkan kamu: frame terakhir sebelum [DONE] membawa usage yang sebenarnya.

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"}}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Halo"}}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":9,"total_tokens":21}}

data: [DONE]

Begitu byte pertama terkirim, permintaan tidak bisa dialihkan ke penyedia lain — jawaban yang sudah setengah tampil tidak bisa ditarik kembali. Kegagalan di tengah stream karena itu berakhir sebagai stream yang terpotong, bukan sebagai percobaan ulang diam-diam.

SDK resmi OpenAI bekerja tanpa modifikasi: cukup ganti baseURL dan pakai API key FreeAPIKey sebagai apiKey. Yang sudah kami pastikan bekerja adalah chat.completions.create (biasa maupun streaming) dan models.list.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FREEAPIKEY_API_KEY,
  baseURL: "https://v1.freeapikey.site/v1",
});

const completion = await client.chat.completions.create({
  model: "MODEL_ID",
  messages: [{ role: "user", content: "Halo, apa kabar?" }],
});

console.log(completion.choices[0]?.message.content);

Bagian SDK yang memanggil endpoint di luar keduanya — embeddings, images, audio, assistants, batches — tidak akan bekerja, karena gateway ini memang tidak memasang endpoint tersebut.

Tabel ini dibangun dari registry error yang sama dengan yang dipakai server, jadi kode dan status HTTP di bawah adalah yang benar-benar dikirim — bukan salinan yang bisa tertinggal.

Error yang ditandai Retry-After mengirim header dengan nama itu. Hormati nilainya; mencoba ulang lebih cepat hanya memperbesar antrean yang sudah penuh.

Ada dua hal yang benar-benar membatasi permintaanmu di gateway, dan keduanya bekerja dengan cara yang berbeda.

Kuota token harian

Paket gratis mendapat 10 juta token per hari. Hitungannya berbasis hari UTC: hari baru adalah baris baru, jadi kuota berganti tepat pada 00:00 UTC tanpa perlu direset. Melewatinya dijawab QUOTA_EXCEEDED.

Permintaan bersamaan

Paket gratis boleh menjalankan 2 permintaan sekaligus, Pro 10. Batas ini soal berapa yang berjalan pada saat yang sama, bukan berapa banyak per menit — 30 permintaan berurutan dan 30 permintaan serentak sangat berbeda bagi penyedia di hulu. Melewatinya dijawab CONCURRENCY_LIMIT; jawabannya adalah menurunkan paralelisme, bukan mempercepat retry.

Batas lain

• Body permintaan maksimal 2 MB.
• Endpoint autentikasi platform — daftar, masuk, kirim ulang kode — punya batas percobaannya sendiri dan menjawab TOO_MANY_ATTEMPTS.
• Angka-angka di atas adalah konfigurasi, bukan janji kontraktual: operator dapat menyesuaikannya, dan halaman ini akan menyusul.

Masa aktif paket gratis bisa diperpanjang dengan mengajak developer lain: 1 referral menambah 3 hari, 3 referral menambah 7 hari, 10 referral menambah 30 hari.

Sebuah referral dihitung hanya setelah orang yang kamu ajak memverifikasi Gmail-nya, lolos pemeriksaan risiko, membuat API key, dan benar-benar memakainya sampai ambang penggunaan tertentu dalam jendela waktu yang berlaku. Klik pada tautan tidak dihitung, dan mengajak diri sendiri tidak dihitung.

Aturan itu bukan formalitas: justru itu yang membuat kuota gratis ini masih bisa ada. Kode referral dan tautannya tersedia di dasbor setelah kamu masuk.