Lewati ke konten
Dokumentasi developer

Dokumentasi API CutadAI.

Referensi endpoint dan panduan integrasi CutadAI. Seluruh endpoint model diakses melalui satu base URL yang kompatibel dengan format OpenAI.

Base URLhttps://ai.cutad.web.id/v1
Panduan

Memulai

Kirim request pertama dalam tiga langkah. Apabila aplikasi Anda sudah menggunakan SDK OpenAI, integrasi umumnya hanya memerlukan perubahan base URL dan API key.

  1. 1
    Buat API key

    Masuk ke Dashboard → API Keys lalu buat key baru. Simpan key di sisi server atau pengelola rahasia; jangan menaruhnya di kode aplikasi klien.

  2. 2
    Atur base URL

    Arahkan klien OpenAI-compatible Anda ke https://ai.cutad.web.id/v1.

  3. 3
    Kirim request pertama

    Pilih model dari GET /v1/models, kemudian gunakan nama model tersebut pada request Chat Completions.

curl https://ai.cutad.web.id/v1/chat/completions \
  -H "Authorization: Bearer <API_KEY_ANDA>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [{ "role": "user", "content": "Halo" }]
  }'

Untuk Python, pasang SDK terlebih dahulu dengan pip install openai. Contoh di atas menggunakan model deepseek-v4.1-flash; ganti dengan model lain yang tersedia untuk akun Anda.

Panduan

Autentikasi

Seluruh request ke endpoint model harus menyertakan API key pada header Authorization.

http
Authorization: Bearer <API_KEY_ANDA>
  • API key dibuat dan dicabut dari Dashboard → API Keys. Key diawali prefiks cag_.
  • Key disimpan di server dalam bentuk hash SHA-256; CutadAI tidak menyimpan key dalam bentuk aslinya.
  • Apabila key diduga bocor, segera cabut key tersebut dari dashboard dan buat key baru. Request tanpa header yang valid ditolak dengan status 401.
Referensi

Referensi endpoint

Daftar endpoint yang aktif pada layanan saat ini. Daftar ini dimuat dari konfigurasi layanan, sehingga selalu mengikuti endpoint yang diterbitkan administrator.

GEThttps://ai.cutad.web.id/v1/modelsMemerlukan API key

List Models

Mengembalikan daftar semua model yang tersedia di gateway.

Header

  • Authorization: Bearer <API_KEY_ANDA> pada setiap request.
  • Content-Type: application/json untuk request yang memiliki body.

Parameter

Endpoint ini tidak memerlukan body maupun parameter query.

Contoh request

bash
curl https://ai.cutad.web.id/v1/models \
  -H "Authorization: Bearer <API_KEY_ANDA>"

Contoh respons

json — 200
{
  "object": "list",
  "data": [
    {
      "id": "deepseek-v4.1-flash",
      "object": "model",
      "created": 1750000000,
      "owned_by": "cutad",
      "display_name": "DeepSeek V4.1 Flash",
      "context_window": 128000,
      "max_output_tokens": 8192,
      "description": null,
      "capabilities": null
    }
  ]
}

Catatan

Daftar yang dikembalikan sudah disaring mengikuti paket Anda: model yang tidak termasuk dalam paket tidak ditampilkan.
POSThttps://ai.cutad.web.id/v1/responsesMemerlukan API key

responses

Header

  • Authorization: Bearer <API_KEY_ANDA> pada setiap request.
  • Content-Type: application/json untuk request yang memiliki body.

Parameter

ParameterTipeWajibKeterangan
modelstringWajibNama model publik yang mendukung format Responses API.
inputstring / arrayWajibMasukan untuk model, berupa teks atau daftar item masukan sesuai format Responses API.
instructionsstringOpsionalInstruksi tingkat sistem yang memandu perilaku model.
streambooleanOpsionalBila true, event respons dikirim bertahap sebagai Server-Sent Events.
max_output_tokensintegerOpsionalBatas token keluaran untuk respons ini.
temperaturenumberOpsionalMengatur variasi keluaran. Ketersediaan mengikuti model yang dipilih.

Contoh body request

json
{
  "model": "deepseek-v4.1-flash",
  "input": "Halo, jelaskan secara singkat apa itu API gateway."
}

Contoh respons

json — 200
{
  "id": "resp_xxxxxxxxxxxxxxxx",
  "object": "response",
  "created_at": 1750000000,
  "model": "deepseek-v4.1-flash",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "API gateway adalah …" }]
    }
  ],
  "usage": { "input_tokens": 18, "output_tokens": 42, "total_tokens": 60 }
}

Catatan

Format Responses API. Ketersediaan dan perilaku parameter mengikuti model yang dipilih; untuk kompatibilitas terluas dengan SDK dan agent, gunakan Chat Completions.
POSThttps://ai.cutad.web.id/v1/chat/completionsMemerlukan API key

Chat Completion

Membuat completion obrolan format OpenAI-compatible.

Header

  • Authorization: Bearer <API_KEY_ANDA> pada setiap request.
  • Content-Type: application/json untuk request yang memiliki body.

Parameter

ParameterTipeWajibKeterangan
modelstringWajibNama model publik, misalnya deepseek-v4.1-flash. Lihat GET /v1/models untuk daftar yang tersedia bagi akun Anda.
messagesarrayWajibDaftar pesan percakapan dengan role system, user, assistant, atau tool beserta content-nya.
streambooleanOpsionalBila true, respons dikirim bertahap sebagai Server-Sent Events. Default false.
temperaturenumberOpsionalMengatur variasi keluaran (umumnya 0–2). Ketersediaan dan rentang mengikuti model yang dipilih.
top_pnumberOpsionalAlternatif temperature untuk nucleus sampling. Gunakan salah satu, bukan keduanya sekaligus.
max_tokensintegerOpsionalBatas token keluaran. Prompt dan batas ini tidak boleh melampaui jendela konteks model.
toolsarrayOpsionalDaftar definisi function/tool yang dapat dipanggil model. Dukungan bergantung pada model.
tool_choicestring / objectOpsionalMengatur pemanggilan tool, misalnya auto, none, atau nama fungsi tertentu. Dukungan bergantung pada model.

Contoh body request

json
{
  "model": "deepseek-v4.1-flash",
  "messages": [
    { "role": "user", "content": "Halo, jelaskan secara singkat apa itu API gateway." }
  ],
  "stream": false
}

Contoh respons

json — 200
{
  "id": "chatcmpl-xxxxxxxxxxxxxxxx",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "deepseek-v4.1-flash",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "API gateway adalah …" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 18, "completion_tokens": 42, "total_tokens": 60 }
}
POSThttps://ai.cutad.web.id/v1/embeddingsMemerlukan API key

Embeddings

Menghasilkan embedding vektor untuk teks input.

Header

  • Authorization: Bearer <API_KEY_ANDA> pada setiap request.
  • Content-Type: application/json untuk request yang memiliki body.

Parameter

ParameterTipeWajibKeterangan
modelstringWajibNama model embedding yang tersedia bagi akun Anda.
inputstring / arrayWajibTeks yang akan diubah menjadi vektor embedding; dapat berupa satu teks atau daftar teks.
encoding_formatstringOpsionalFormat keluaran vektor, misalnya float. Ketersediaan mengikuti model yang dipilih.

Contoh body request

json
{
  "model": "nama-model-embedding",
  "input": "teks yang akan diubah menjadi embedding"
}

Contoh respons

json — 200
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, 0.0789]
    }
  ],
  "model": "nama-model-embedding",
  "usage": { "prompt_tokens": 8, "total_tokens": 8 }
}

Catatan

Nilai vektor pada contoh respons disingkat. Panjang vektor mengikuti model embedding yang digunakan.
Panduan

Streaming

Chat Completions dan Responses mendukung pengiriman respons bertahap melalui Server-Sent Events (SSE).

Atur parameter stream menjadi true pada request. Setiap potongan respons dikirim sebagai baris data: dan aliran diakhiri dengan data: [DONE].

text — potongan SSE
data: {"choices":[{"index":0,"delta":{"role":"assistant","content":"Halo"}}]}

data: {"choices":[{"index":0,"delta":{"content":" dunia"}}]}

data: [DONE]
  • Pada Chat Completions, gateway menambahkan stream_options.include_usage secara otomatis apabila belum diatur, sehingga ringkasan pemakaian token dikirim pada potongan terakhir.
  • Kesalahan yang terjadi di tengah aliran dikirim dalam format SSE yang sama sebelum aliran ditutup.
  • Jangan mengulangi request streaming secara otomatis dari tengah aliran; kirim ulang request dari awal apabila koneksi terputus.
Panduan

Batas pemakaian dan kredit

Batas berikut ditentukan oleh paket langganan Anda dan diperiksa pada setiap request.

  • Batas per menit. Jumlah request per pengguna dibatasi dalam jendela 60 detik sesuai paket.
  • Batas request bersamaan. Jumlah request yang sedang diproses secara bersamaan dibatasi sesuai paket.
  • Kuota per periode. Total request dalam satu periode langganan dibatasi sesuai paket dan dihitung dari awal periode berjalan.
  • Kredit token. Pada paket yang mengaktifkan kredit, pemakaian dihitung dari total token masukan dan keluaran setiap request yang berhasil, lalu mengurangi saldo kredit paket. Saldo diperbarui pada awal periode berikutnya (harian, mingguan, atau bulanan, mengikuti paket).

Respons menyertakan header berikut:

HeaderKeterangan
x-ratelimit-remainingSisa request dalam jendela 60 detik berjalan.
x-ratelimit-resetWaktu berakhirnya jendela berjalan, dalam milidetik sejak epoch Unix.
retry-afterJumlah detik yang perlu ditunggu sebelum mencoba kembali. Hanya dikirim bersama respons 429.

Apabila kredit habis, gateway mengembalikan status 429 dengan bentuk berikut:

json — 429 kredit habis
{
  "error": {
    "message": "Credit exhausted. 100000 tokens/monthly. Resets …",
    "type": "quota_exceeded",
    "code": "insufficient_quota",
    "param": null,
    "credits": { "remaining": 0, "limit": 100000, "resetPeriod": "MONTHLY" }
  }
}
Lanjutan

Webhook

Pada paket yang mengaktifkan webhook, CutadAI mengirim pemberitahuan ke URL Anda setiap kali sebuah request selesai diproses dengan berhasil.

Daftarkan URL dan pilih event di Dashboard → Webhooks. Saat ini tersedia satu event:

EventKeterangan
request.completedRequest API selesai dengan status berhasil (di bawah 400).

Setiap pengiriman berupa POST JSON dengan bentuk berikut:

json — payload webhook
{
  "event": "request.completed",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "data": {
    "endpoint": "/v1/chat/completions",
    "method": "POST",
    "status": 200,
    "latencyMs": 150
  }
}
  • Header x-webhook-event berisi nama event dan x-webhook-secret berisi secret yang Anda atur pada dashboard.
  • Verifikasi pengiriman dengan membandingkan header x-webhook-secret terhadap secret Anda menggunakan perbandingan waktu-konstan, misalnya hmac.compare_digest pada Python.
  • Setiap pengiriman dicatat beserta status keberhasilannya pada riwayat webhook di dashboard.
Lanjutan

Kode kesalahan

Seluruh kesalahan dikembalikan dalam format objek error yang kompatibel dengan OpenAI, disertai kode status HTTP.

json — bentuk umum kesalahan
{
  "error": {
    "message": "Invalid or revoked API key",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}
KodeKondisiPenjelasan dan tindakan
400context_length_exceededTotal token prompt dan batas keluaran melampaui jendela konteks model. Kurangi isi percakapan atau nilai max_tokens.
401invalid_api_keyHeader Authorization tidak ada, atau key tidak ditemukan, tidak aktif, atau telah dicabut. Periksa key Anda di dashboard.
403Akun atau langganan tidak aktifAkun dinonaktifkan atau tidak memiliki langganan aktif. Periksa status langganan Anda di dashboard.
403model_not_allowedModel yang diminta tidak termasuk dalam paket Anda. Gunakan model yang tersedia bagi paket Anda atau naikkan paket.
404model_not_foundModel tidak tersedia di gateway. Periksa nama model melalui GET /v1/models.
413request_too_largeBody request melebihi batas 10 MB atau batas payload model. Kurangi ukuran percakapan atau lampiran.
429rate_limit_exceededBatas request per menit terlampaui. Tunggu sesuai header retry-after sebelum mencoba kembali.
429concurrency_limit_exceededJumlah request bersamaan mencapai batas paket. Tunggu hingga request yang berjalan selesai.
429insufficient_quotaKuota request periode ini terlampaui atau kredit token habis. Periksa pemakaian Anda di dashboard.
502upstream_errorLayanan model di hulu tidak dapat dijangkau atau mengembalikan kesalahan. Coba kembali setelah beberapa saat.
503circuit_openLayanan model di hulu sedang mengalami gangguan beruntun dan dijeda sementara. Coba kembali setelah beberapa detik.
Pesan kesalahan dari layanan model di hulu disaring sebelum diteruskan, sehingga informasi internal penyedia dan isi percakapan Anda tidak terekspos pada respons kesalahan.
Lanjutan

Pengulangan dan batas waktu

Ketentuan berikut membantu aplikasi Anda menangani kegagalan sementara dengan benar.

  • Hormati header retry-after. Pada respons 429, tunggu selama nilai header tersebut sebelum mengirim request berikutnya.
  • Ulangi hanya kesalahan sementara. Status 429, 502, dan 503 serta kegagalan jaringan dapat diulangi dengan jeda yang meningkat (misalnya 1, 2, lalu 4 detik, ditambah jitter acak) hingga jumlah percobaan yang wajar.
  • Jangan mengulangi kesalahan permintaan. Status 400, 401, 403, 404, dan 413 akan kembali gagal hingga penyebabnya diperbaiki.
  • Atur batas waktu di klien. Request non-streaming yang menghasilkan keluaran panjang dapat memerlukan waktu lebih lama; sesuaikan timeout klien Anda dan gunakan streaming untuk respons yang panjang.
Memerlukan bantuan teknis? Sampaikan kendala Anda melalui halaman kontak dengan mencantumkan waktu kejadian, endpoint, dan kode status yang diterima.