Responses

Buat response model dengan format OpenAI Responses. Ini adalah subset stateless yang dibuat untuk agen coding seperti Codex, dan SDK resmi OpenAI langsung bisa dipakai setelah base URL diarahkan ke https://kenari.id/v1. Untuk konfigurasi Codex, lihat Codex.

POST /v1/responses

Autentikasi dengan Authorization: Bearer kn-.... Lihat Autentikasi & API key.

Stateless

kenari tidak menyimpan apa pun di antara request, jadi kirim seluruh percakapan di input setiap kali.

• previous_response_id selain null mengembalikan 400.
• store diterima dan diabaikan.
• Tidak ada endpoint untuk mengambil, menampilkan daftar, atau menghapus response.

Request

Field	Tipe	Wajib	Keterangan
model	string	Ya	Id katalog, id :free, nama rute, atau id byok/. Nilainya sama dengan di Chat completions.
input	string atau array	Ya	String dianggap satu pesan user. Array berisi item input. Tidak boleh kosong.
instructions	string	Tidak	Instruksi sistem. Digabung dengan item developer di awal bila ada.
tools	array	Tidak	Function tool datar, masing-masing dengan type bernilai function, serta name, description, dan parameters. Function tool tanpa name mengembalikan 400. Server tools kenari seperti {"type": "kenari:web_search"} juga bisa dipakai. Jenis tool lain dibuang tanpa error. Lihat Function calling dan Server tools.
tool_choice	string atau object	Tidak	auto, none, required, atau {"type": "function", "name": "get_weather"} untuk memaksa satu fungsi. Selain itu mengembalikan 400.
reasoning	object atau null	Tidak	{"effort": "low"}. Tingkatnya none, minimal, low, medium, high, xhigh, dan max. summary diterima dan diabaikan. Lihat Penalaran.
max_output_tokens	integer	Tidak	Batas atas token yang dihasilkan, termasuk penalaran. Bawaan 65.536.
temperature	number	Tidak	Temperatur sampling.
top_p	number	Tidak	Nucleus sampling.
stream	boolean	Tidak	Setel true untuk menerima Server-Sent Events. Lihat Streaming.
text	object	Tidak	Hanya {"format": {"type": "text"}} yang diterima. Format lain mengembalikan 400. Untuk output JSON, pakai Chat completions dan lihat Output terstruktur.
prompt_cache_key	string	Tidak	Id tetap untuk satu percakapan, supaya request lanjutan memakai ulang prefix yang sudah di-cache. Maksimal 512 byte. Nilai yang lebih panjang atau kosong diabaikan. Lihat Prompt caching.
previous_response_id	string atau null	Tidak	Harus tidak ada atau null.
store	boolean	Tidak	Diterima dan diabaikan.
include	array	Tidak	Diterima dan diabaikan.
metadata	object	Tidak	Diterima dan diabaikan.
parallel_tool_calls	boolean	Tidak	Diterima dan diabaikan.

Item input

Item	Field	Catatan
Message	role, content	role adalah system, developer, user, atau assistant. type boleh dihilangkan. content berupa string atau array bagian.
Function call	type bernilai function_call, call_id, name, arguments	Panggilan yang dibuat model sebelumnya. arguments berupa string JSON.
Hasil fungsi	type bernilai function_call_output, call_id, output	Hasil sebuah panggilan. output berupa string atau array bagian teks.
Reasoning	type bernilai reasoning, summary (sebuah array)	Penalaran sebelumnya, dikembalikan ke model.

Pesan system dan developer di awal digabung ke system prompt. Jenis item yang tidak dikenal dibuang tanpa error, dan role lain mengembalikan 400.

Bagian pesan yang didukung adalah input_text dan output_text, serta input_image dengan string image_url, yang hanya diterima di pesan user dan assistant (di pesan developer hasilnya 400). Bagian input_file mengembalikan 400. Untuk dokumen, pakai Chat completions: bagian file bekerja di model apa pun. Lihat Gambar & berkas sebagai input dan Baca dokumen.

Response

Response berupa objek response. Array output berisi item yang dihasilkan model, berurutan.

{
  "id": "resp_4f1c9a2e7b3d5a60",
  "object": "response",
  "created_at": 1790000000,
  "status": "completed",
  "model": "step-3-7-flash:free",
  "output": [
    {
      "type": "message",
      "id": "msg_1",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Halo! Ada yang bisa dibantu?" }]
    }
  ],
  "usage": {
    "input_tokens": 9,
    "output_tokens": 12,
    "total_tokens": 21,
    "input_tokens_details": { "cached_tokens": 0 }
  }
}

Item output	Keterangan
reasoning	Penalaran model sebagai satu entri summary_text. Berada paling depan di array, dan hanya ada bila model bernalar.
message	Jawabannya, di dalam bagian output_text.
function_call	Fungsi yang diminta model untuk kamu jalankan: call_id, name, dan arguments sebagai string JSON. Jalankan, lalu kirim item function_call_output dengan call_id yang sama di request berikutnya.

status bernilai completed, atau incomplete dengan incomplete_details.reason berisi max_output_tokens bila jawaban terpotong oleh batas. usage.input_tokens_details.cached_tokens menghitung input yang dilayani dari cache dan sudah termasuk dalam input_tokens.

Setelah menjalankan fungsi, kirim request lanjutan yang membawa panggilan sebelumnya dan hasilnya di input:

{
  "model": "step-3-7-flash:free",
  "input": [
    { "role": "user", "content": "Bagaimana cuaca di Jakarta?" },
    {
      "type": "function_call",
      "call_id": "call_1",
      "name": "get_weather",
      "arguments": "{\"city\": \"Jakarta\"}"
    },
    { "type": "function_call_output", "call_id": "call_1", "output": "31 C dan cerah" }
  ],
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Ambil cuaca saat ini untuk sebuah kota.",
      "parameters": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }
  ]
}

Streaming

Setel "stream": true untuk menerima response sebagai Server-Sent Events. Urutan event ada di Streaming.

Contoh

curl

curl https://kenari.id/v1/responses \
  -H "Authorization: Bearer $KENARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "step-3-7-flash:free",
    "instructions": "Kamu menjawab dengan singkat.",
    "input": "Halo!"
  }'

Python

import os
from openai import OpenAI

client = OpenAI(base_url="https://kenari.id/v1", api_key=os.environ["KENARI_API_KEY"])

response = client.responses.create(
    model="step-3-7-flash:free",
    instructions="Kamu menjawab dengan singkat.",
    input="Halo!",
)
print(response.output_text)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://kenari.id/v1",
  apiKey: process.env.KENARI_API_KEY,
});

const response = await client.responses.create({
  model: "step-3-7-flash:free",
  instructions: "Kamu menjawab dengan singkat.",
  input: "Halo!",
});
console.log(response.output_text);

Penagihan

Setiap request ditagih per token sesuai harga Input, Output, Cache read, dan Cache write model tersebut. Model :free tidak dikenai biaya. Lihat Cara penagihan.

Error

Error memakai envelope OpenAI: objek error dengan message, type, param, dan code. Di sini hanya error yang khusus untuk endpoint ini. Sisanya, seperti model_not_found, context_length_exceeded, dan subscribers_only, ada di Error.

Status	Kode	Kapan
400	bad_request	input tidak ada atau kosong. previous_response_id bukan null. text.format bukan text. Sebuah pesan punya role yang tidak dikenal. Ada bagian input_file. Sebuah function tool tidak punya name. tool_choice bukan salah satu bentuk yang didukung.
400	bad_request	Model bukan model chat, seperti model gambar atau suara. Pesan errornya menyebut endpoint yang harus dipakai.

Lihat juga

• Codex
• Streaming
• Function calling
• Chat completions