Cara Menggunakan OpenAI Responses API

Panduan ini memandu Anda dalam menggunakan OpenAI Responses API dari awal hingga akhir: pada saat Anda selesai, Anda akan dapat mengirim permintaan ke POST /v1/responses, membaca output bersarang yang dikembalikannya, mengaktifkan alat bawaan, membawa status percakapan antar panggilan, dan memverifikasi seluruh kontrak di dalam Apidog. Responses API adalah antarmuka OpenAI yang lebih baru untuk menghasilkan output model, dan panduan resmi Responses menjelaskan mengapa OpenAI kini mengarahkan proyek baru ke sana. Jika Anda sudah menguji endpoint yang lebih lama, Anda dapat menggunakan kembali sebagian besar pengaturan tersebut, mirip dengan alur kerja dalam panduan pengujian ChatGPT API kami.

Tombol

Apa yang Anda butuhkan terlebih dahulu

Sebelum mengirim permintaan, pastikan Anda memiliki beberapa hal:

Kunci API OpenAI dengan akses ke model serbaguna saat ini. Simpan kunci di variabel lingkungan, bukan ditempelkan ke perintah atau file bersama.
Nama model yang dapat diakses oleh akun Anda. Daripada mengkodekannya secara langsung, periksa daftar model di dasbor OpenAI Anda dan konfirmasikan dengan endpoint.
Cara untuk mengirim permintaan HTTP mentah dan memeriksa JSON yang kembali. Terminal dengan curl berfungsi untuk panggilan pertama, dan Apidog adalah yang akan Anda gunakan untuk melakukan penegasan dan mem-mock respons nanti.

Juga membantu untuk mengetahui apa yang dilakukan endpoint sebelum Anda memanggilnya. Responses API mengekspos satu endpoint, POST /v1/responses. Anda mengirim nama model dan sebuah input, dan Anda mendapatkan kembali objek respons yang dapat berisi teks biasa, panggilan fungsi, dan hasil dari alat yang di-host OpenAI seperti pencarian web atau pencarian file. Satu panggilan dapat menjalankan seluruh giliran multi-langkah: model memutuskan untuk mencari web, membaca hasilnya, lalu menulis jawaban, dan respons mencatat setiap langkah yang diambilnya.

Dua hal yang membedakannya dari endpoint teks biasa. Pertama, ia dapat menjalankan alat bawaan di sisi server, jadi Anda tidak perlu menyiapkan pencarian atau sandbox Anda sendiri. Kedua, ia bersifat stateful secara default. Setiap respons mendapatkan id, dan Anda dapat menyerahkan id tersebut ke permintaan berikutnya sehingga OpenAI menyimpan riwayat percakapan untuk Anda. OpenAI mendeskripsikan Responses API sebagai evolusi dari Chat Completions dan merekomendasikannya untuk proyek baru, menggabungkan pelajaran dari beta Assistants API. Jadi alih-alih tiga model mental, Anda mendapatkan satu.

Ketahuilah perbedaannya dari Chat Completions

Jika Anda pernah menggunakan POST /v1/chat/completions, pergeseran sebagian besar ada pada bentuk dan status. Chat Completions mengambil array messages dan mengembalikan choices. Anda mengelola seluruh transkrip sendiri, mengirim ulang setiap giliran sebelumnya pada setiap panggilan. Alat adalah sesuatu yang Anda terapkan di sisi Anda.

Responses API mengambil input (string atau daftar item bertipe) dan mengembalikan output (daftar item bertipe). Ini dapat menyimpan giliran untuk Anda dan menjalankan alat yang di-host tanpa perlu penyiapan tambahan.

Berikut perbandingan praktisnya:

Aspek	Chat Completions	Responses API
Endpoint	`POST /v1/chat/completions`	`POST /v1/responses`
Isi permintaan	Array `messages`	`input` (string atau item) + `instructions`
Bentuk output	`choices[].message`	Daftar `output` item bertipe
Status percakapan	Anda mengirim ulang seluruh riwayat	`store` + `previous_response_id`
Alat bawaan	Anda membangunnya	`web_search`, `file_search`, `code_interpreter`, dan lainnya
Status	Didukung, tidak ada pengumuman penghentian	Direkomendasikan untuk proyek baru

Chat Completions tidak akan hilang. OpenAI mengatakan itu tetap didukung, dan Anda dapat memigrasikan satu alur pengguna pada satu waktu daripada menulis ulang semuanya sekaligus. Assistants API adalah yang akan dihentikan: OpenAI menghentikannya pada 26 Agustus 2025, dengan penghentian yang direncanakan pada 26 Agustus 2026, jadi pekerjaan agen baru harus dimulai dengan Responses.

Lakukan permintaan pertama Anda

Berikut adalah panggilan minimal. Ganti nama model dengan apa pun yang dapat diakses oleh akun Anda, dan jangan sertakan kunci Anda dalam perintah itu sendiri.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Write one sentence describing what an API mock server does.",
    "instructions": "You are a concise technical writer. No marketing language.",
    "store": true
  }'

Anda meneruskan tiga hal penting di sini: model, input (prompt Anda), dan instructions (arahan tingkat sistem). Menyetel store ke true memberi tahu OpenAI untuk menyimpan respons sehingga Anda dapat melanjutkan utas nanti.

Baca responsnya

Respons yang dipangkas terlihat seperti ini:

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A mock server returns predefined API responses so clients can be developed and tested before the real backend exists."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 28,
    "output_tokens": 24,
    "total_tokens": 52
  }
}

Perhatikan strukturnya, karena inilah bagian yang sering membingungkan orang. Teks yang Anda inginkan berada di output[0].content[0].text, bukan di bidang tingkat atas. SDK resmi menambahkan aksesori kenyamanan output_text yang mengagregasikan semua item teks menjadi satu string, tetapi properti tersebut adalah pembantu SDK, bukan bagian dari JSON HTTP mentah. Ketika Anda memanggil endpoint secara langsung, Anda membaca jalur bersarang. id tingkat atas adalah yang akan Anda gunakan kembali untuk status, dan usage.total_tokens memberi tahu Anda berapa biaya panggilan.

Tambahkan alat bawaan

Fitur utamanya adalah OpenAI menjalankan alat tertentu untuk Anda. Anda mencantumkannya dalam array tools dan model memutuskan kapan akan memanggilnya. Jenis bawaan yang terverifikasi meliputi:

web_search untuk pencarian internet langsung dengan kutipan (`web_search_preview` yang lebih lama masih berfungsi untuk integrasi lama tetapi tidak memiliki kontrol yang lebih baru).
file_search untuk pengambilan di seluruh file yang Anda unggah.
code_interpreter untuk menjalankan dan menganalisis kode dalam sandbox.
computer_use untuk mengoperasikan antarmuka komputer.
image_generation untuk menghasilkan gambar secara langsung.

Mengaktifkan salah satunya adalah tambahan kecil pada body:

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [{ "type": "web_search" }]
}

Ketika model menggunakan alat, array output mendapatkan entri yang mendokumentasikan langkah tersebut, seperti item web_search_call di samping message akhir. Itu berguna nanti: Anda dapat memeriksa apakah alat benar-benar diaktifkan, bukan hanya teks yang kembali.

Lanjutkan percakapan antar panggilan

Status bekerja melalui dua parameter. store secara default bernilai true, yang berarti OpenAI menyimpan objek respons (disimpan selama 30 hari secara default) dan mengembalikan id. Teruskan id tersebut sebagai previous_response_id pada panggilan Anda berikutnya dan model akan melanjutkan utas tanpa Anda mengirim ulang transkrip:

{
  "model": "gpt-5.5",
  "input": "Now rewrite that for a non-technical audience.",
  "previous_response_id": "resp_abc123"
}

Jika Anda lebih suka menjaga semuanya tanpa status, atau Anda memiliki persyaratan retensi data nol, atur store ke false dan kelola konteks sendiri. Untuk alur suara dan audio real-time, latensi rendah, OpenAI menggunakan permukaan yang berbeda; panduan GPT realtime API kami mencakup kasus tersebut. Dan jika Anda mengatur agen multi-langkah di atas semua ini, polanya selaras dengan OpenAI Agents SDK.

Cara mengujinya di Apidog

Apidog adalah platform pengujian, desain, dan mock API. Ini bukan OpenAI SDK atau library kode, jadi Anda tidak akan menulis Python melawannya. Yang Anda lakukan sebagai gantinya: bangun permintaan HTTP mentah ke /v1/responses, kirimkan, dan tulis asersi pada JSON yang kembali. Itulah jenis pemeriksaan kontrak yang menangkap integrasi yang rusak sebelum pengguna Anda mengetahuinya.

Berikut adalah penyiapan, langkah demi langkah.

Simpan kunci di variabel lingkungan

Di Apidog, buat lingkungan (misalnya, "OpenAI Prod") dan tambahkan variabel seperti OPENAI_API_KEY. Simpan nilai di lingkungan, bukan di permintaan, agar rahasia tidak pernah dikomit ke koleksi bersama. Kemudian bangun permintaan POST baru ke https://api.openai.com/v1/responses dan tambahkan header Authorization: Bearer {{OPENAI_API_KEY}}. Apidog menggantikan variabel pada saat pengiriman.

Atur body ke JSON dan tempelkan permintaan dari sebelumnya. Tekan kirim. Anda akan melihat objek respons lengkap, diformat, dengan array output bersarang.

Lakukan asersi pada bidang respons

Respons 200 yang berhasil bukanlah bukti bahwa respons tersebut berbentuk seperti yang diharapkan aplikasi Anda. Tambahkan asersi agar regresi gagal dengan jelas. Pemeriksaan yang berguna terhadap balasan /v1/responses:

status sama dengan completed.
output[0].content[0].text ada dan tidak kosong.
usage.total_tokens lebih besar dari 0.
Ketika Anda mengirim tools, sebuah item di output memiliki type sama dengan web_search_call.

Pembuat asersi visual Apidog memungkinkan Anda menargetkan jalur JSON tersebut tanpa menulis skrip pengujian, dan templat kasus uji API kami menunjukkan cara menyusun pemeriksaan seperti ini. Simpan permintaan ke dalam koleksi dan itu menjadi pengujian berulang yang dapat Anda jalankan di CI.

Mock respons untuk pengembangan offline

Panggilan OpenAI memakan biaya dan memerlukan akses jaringan, yang canggung saat Anda membangun UI yang mengonsumsi respons atau menjalankan pengujian dalam pipeline yang seharusnya tidak memanggil API berbayar. Fitur mock Apidog memecahkan masalah itu. Simpan payload /v1/responses yang representatif sebagai mock, arahkan aplikasi Anda ke URL mock Apidog, dan frontend Anda akan mendapatkan bentuk JSON yang benar dengan nol pengeluaran token. Ketika endpoint yang sebenarnya berubah, Anda memperbarui satu mock alih-alih mengejar kegagalan di setiap pengujian. Penjelasan API mock kami membahas pendekatan umum.

Pemecahan ini penting. Anda menguji terhadap endpoint langsung untuk memverifikasi kontrak OpenAI, dan Anda mem-mock-nya untuk pengembangan yang cepat, offline, dan deterministik. Keduanya berjalan dari proyek Apidog yang sama.

Pertanyaan yang Sering Diajukan

Apakah Responses API menggantikan Chat Completions?

Tidak secara paksa. OpenAI menyebut Responses sebagai evolusi dari Chat Completions dan merekomendasikannya untuk proyek baru, tetapi Chat Completions tetap didukung tanpa tanggal penghentian yang diumumkan. Anda dapat memigrasikan satu alur pada satu waktu. Assistants API adalah yang akan dihentikan, dengan tanggal penghentian pada tahun 2026.

Apa perbedaan antara `store` dan `previous_response_id`?

store mengontrol apakah OpenAI menyimpan objek respons sama sekali (secara default bernilai true dan dipertahankan selama 30 hari). previous_response_id adalah cara Anda menautkan permintaan baru ke permintaan yang disimpan sehingga model melanjutkan percakapan di sisi server. Anda menggunakannya bersama untuk utas stateful, dan mematikan store ketika Anda menginginkan perilaku stateless.

Model mana yang mendukung Responses API?

Model serbaguna OpenAI saat ini dirancang untuk bekerja dengan Responses API, tetapi ketersediaan tergantung pada akun Anda dan model yang Anda pilih. Daripada mengkodekan nama model secara langsung, periksa daftar model di dasbor OpenAI Anda, lalu konfirmasikan dengan endpoint. Mengirim permintaan cepat melalui Apidog dan membaca bidang model dalam respons adalah cara cepat untuk memverifikasi apa yang sebenarnya dapat dipanggil oleh kunci Anda.

Bisakah saya menguji alat bawaan tanpa menulis kode?

Ya. Tambahkan array tools ke body JSON di Apidog, kirim permintaan, dan asumsikan bahwa item panggilan alat yang cocok (seperti web_search_call) muncul di array output. Anda memeriksa perilaku OpenAI melalui HTTP, jadi tidak diperlukan SDK. Untuk menguji panggilan alat agen secara lebih luas, lihat cara menghasilkan koleksi pengujian API dari spesifikasi OpenAPI.

Ringkasan

Anda sekarang memiliki siklus penuh: satu endpoint, POST /v1/responses, yang menangani teks, alat yang di-host, dan status percakapan sisi server. Kirim permintaan, baca output bersarang, tambahkan array tools saat Anda memerlukan pencarian atau eksekusi kode, dan hubungkan previous_response_id untuk menjaga utas tetap berjalan. Karena bentuknya berbeda dari Chat Completions, langkah teraman adalah memverifikasi kontrak sendiri daripada memercayai memori Anda tentang API yang lebih lama.

Di situlah Apidog berperan. Buat permintaan, simpan kunci Anda sebagai variabel lingkungan, lakukan asersi pada bidang output bersarang, dan mock respons untuk pekerjaan offline, semuanya dalam satu proyek. Unduh Apidog dan arahkan pengujian ke /v1/responses untuk melihat dengan tepat apa yang diterima integrasi Anda. Anda dapat melakukan seluruh penyiapan di Apidog tanpa menulis satu baris pun kode pengujian.