Teks

Buat Respons

Membuat respons menggunakan format OpenAI Responses API

POST
/v1/responses

Gunakan endpoint ini saat accepted_request_formats milik model menyertakan openai_responses. Request dan respons menggunakan format Responses API dan tidak dikonversi: model tanpa format tersebut akan mengembalikan 400 di sini, jadi gunakan Chat Completions untuk model tersebut. Field opsional dan nilai yang didukung bergantung pada model yang dipilih.

Body Permintaan

modelstringwajib

ID model yang akan digunakan. Lihat Models untuk opsi yang tersedia.

inputstring | array

Input untuk respons. Ini bersifat opsional saat request menggunakan prompt yang dapat digunakan kembali atau melanjutkan respons yang tersimpan dengan previous_response_id.

Setiap item adalah objek dengan type. Tipe yang umum adalah:

  • message: Pesan percakapan dengan role dan content
  • function_call: Request pemanggilan fungsi
  • function_call_output: Output dari pemanggilan fungsi
  • reasoning: Item pemikiran dari respons sebelumnya. Kirimkan kembali tanpa diubah

Tipe item lainnya bergantung pada model yang dipilih.

Untuk input multimodal, message.content dapat berupa string teks biasa atau array blok konten. Untuk model yang mendukung gambar, teruskan gambar sebagai blok input_image alih-alih menyematkan URL atau string Base64 langsung ke dalam teks biasa.

Contoh blok konten:

  • { "type": "input_text", "text": "Describe this image" }
  • { "type": "input_image", "image_url": "https://example.com/image.jpg" }
  • { "type": "input_image", "image_url": "data:image/png;base64,..." }
instructionsstring

Instruksi sistem untuk model (setara dengan system message).

max_output_tokensinteger

Jumlah maksimum token yang akan dihasilkan.

temperaturenumber

Suhu sampling. Nilai yang didukung dan nilai default bergantung pada model yang dipilih.

toolsarray

Tool yang dapat dipanggil oleh model. Tipe dan kombinasi yang didukung bergantung pada model yang dipilih.

streambooleanbawaan: false

Jika true, mengembalikan stream event. Lihat Streaming.

previous_response_idstring

ID respons sebelumnya untuk melanjutkan percakapan. Respons harus milik akun Anda dan masih tersimpan; jika tidak, request mengembalikan 404 dengan kode response_not_found. Lanjutkan dengan model yang menghasilkannya. Jika layanan yang menghasilkan respons sementara tidak tersedia, request dapat mengembalikan 503.

storebooleanbawaan: true

Menentukan apakah akan menyimpan respons untuk diambil nanti dan untuk previous_response_id. Dengan false, TokenLab tidak menyimpan respons, dan GET /v1/responses/{id} tidak dapat mengembalikannya.

backgroundbooleanbawaan: false

Meminta eksekusi asinkron. Dukungan bergantung pada model yang dipilih. Panggilan create langsung kembali, biasanya dengan status queued atau in_progress. Lakukan polling pada Ambil respons hingga status bernilai completed, incomplete, failed, atau cancelled. Request latar belakang dapat mengembalikan 503 saat pemrosesan latar belakang sementara tidak tersedia.

tool_choicestring | object

Kebijakan pemilihan tool, seperti auto, none, required, atau objek yang menentukan satu tool. Nilai yang didukung bergantung pada model yang dipilih.

includearray

Bagian output tambahan yang akan dikembalikan, jika didukung oleh model yang dipilih.

stream_optionsobject

Opsi streaming. include_obfuscation diteruskan jika didukung oleh model yang dipilih.

truncationstring

Strategi pemotongan untuk percakapan panjang, jika didukung oleh model yang dipilih.

service_tierstring

TokenLab melayani dan menagih request Responses pada service tier standar. auto dan default diterima. Nilai lain, seperti flex atau priority, dihapus dari request, dan request ditagih dengan harga standar.

promptobject

Referensi ke template prompt yang dapat digunakan kembali dan variabel.

metadataobject

Metadata kustom yang disimpan bersama respons.

textobject

Pengaturan output teks. Dukungan untuk text.format bergantung pada model yang dipilih.

parallel_tool_callsboolean

Menentukan apakah akan mengizinkan beberapa pemanggilan tool secara paralel, jika didukung oleh model yang dipilih.

top_pnumber

Parameter nucleus sampling (0-1).

reasoningobject

Opsi reasoning, termasuk effort, bergantung pada model yang dipilih.

Respons

idstring

Pengidentifikasi unik untuk respons.

objectstring

Selalu response.

created_atinteger

Timestamp Unix saat respons dibuat.

statusstring

Status respons: queued, in_progress, completed, incomplete, failed, atau cancelled. Periksa field ini meskipun HTTP request berhasil.

outputarray

Daftar item output yang dihasilkan oleh model.

usageobject

Statistik penggunaan token.

Endpoint Terkait

  • GET /v1/responses/{id} mengambil respons yang tersimpan.
  • DELETE /v1/responses/{id} menghapus respons yang tersimpan. Endpoint ini tidak membatalkan proses pembuatan (generation).
  • POST /v1/responses/compact memadatkan percakapan dan mengembalikan objek response.compaction.
  • wss://api.tokenlab.sh/v1/responses membuat respons melalui WebSocket. Lihat Streaming.
  • Endpoint cancel, input-items, dan input-tokens saat ini belum tersedia.

Permintaan

cURL
curl -X POST "https://api.tokenlab.sh/v1/responses" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": [
      {"type": "message", "role": "user", "content": "Hello!"}
    ],
    "max_output_tokens": 1000
  }'
Python
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh/v1"
)

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {"type": "message", "role": "user", "content": "Hello!"}
    ],
    max_output_tokens=1000
)

print(response.output)
JavaScript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

const response = await client.responses.create({
  model: 'gpt-5.6-terra',
  input: [
    { type: 'message', role: 'user', content: 'Hello!' }
  ],
  max_output_tokens: 1000
});

console.log(response.output);
Go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "model": "gpt-5.6-terra",
        "input": []map[string]interface{}{
            {"type": "message", "role": "user", "content": "Hello!"},
        },
        "max_output_tokens": 1000,
    }
    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", "https://api.tokenlab.sh/v1/responses", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer sk-your-api-key")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["output"])
}
PHP
<?php
$ch = curl_init('https://api.tokenlab.sh/v1/responses');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer sk-your-api-key'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'gpt-5.6-terra',
        'input' => [
            ['type' => 'message', 'role' => 'user', 'content' => 'Hello!']
        ],
        'max_output_tokens' => 1000
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['output']);

Contoh Input Vision

Gunakan model yang mendukung gambar dengan menempatkan gambar di dalam message.content sebagai blok input_image. Nilai image_url dapat berupa URL publik atau data URL Base64.

{
  "model": "gpt-5.6-terra",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Please describe this image."
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/demo.jpg"
        }
      ]
    }
  ]
}
{
  "model": "gpt-5.6-terra",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Please describe this image."
        },
        {
          "type": "input_image",
          "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
        }
      ]
    }
  ]
}

Respons

Response
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1706000000,
  "status": "completed",
  "model": "gpt-5.6-terra",
  "output": [
    {
      "id": "msg_abc123",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "Hello! How can I help you today?", "annotations": []}
      ]
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 12,
    "total_tokens": 22
  }
}

Error

Error menggunakan objek error bergaya OpenAI. Kasus umum: 400 untuk field yang tidak valid atau model tanpa format Responses, 401 untuk key yang tidak valid, 402 untuk saldo tidak mencukupi, 404 untuk previous_response_id yang tidak diketahui, 429 untuk batas laju (rate limit), dan 503 saat model tidak dapat melayani request saat ini. Lihat Menangani error API.

Otorisasi

BearerAuth
AuthorizationBearer <token>

Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.

Lokasi: header

Header

X-TokenLab-Delivery-Policy?string

Kebijakan Pengiriman per-permintaan. Menggantikan default API key dan Workspace. Secara otomatis mencoba TokenLab Verified terlebih dahulu dan dapat beralih satu kali ke Official saja sebelum output, penerimaan permintaan, atau pembuatan sumber daya persisten.

Nilai yang tersedia

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Kunci opsional yang menghentikan eksekusi kedua dari permintaan yang sama. Kirim nilai unik baru, seperti UUID, untuk setiap permintaan, dan simpan untuk percobaan ulang setelah timeout. Percobaan ulang dengan kunci yang sama tidak akan berjalan lagi: ia mengembalikan 409 dengan idempotency_replay_unavailable, atau biasanya idempotency_conflict jika isi berubah. Pengecualian: jika hasil non-stream selesai setelah klien terputus, percobaan ulang dengan kunci dan isi yang sama dalam waktu 24 jam akan mengembalikan hasil tersebut (hingga 1 MB) dengan header Idempotent-Replayed: true dan tanpa biaya kedua. Kunci yang lebih panjang dari 255 karakter akan diabaikan, dan permintaan tersebut tidak memiliki perlindungan idempotensi. Dengan background: true, percobaan ulang dengan kunci dan isi yang sama akan mengembalikan objek respons asli dan tidak membuat atau menagih respons kedua; isi yang berbeda akan ditolak, dan kode statusnya tidak dijamin. Lihat Retry safely with an idempotency key.

Panjang1 <= length <= 255

Body permintaan

application/json

Respons

application/json

application/json

application/json

application/json

application/json