Text
Create Response
Creates a response using the OpenAI Responses API format
Use this endpoint when a model's accepted_request_formats includes openai_responses. Requests and responses use Responses API format and are not converted: a model without that format returns 400 here, so use Chat Completions for it. Optional fields and supported values depend on the selected model.
Request Body
ID of the model to use. See Models for available options.
Input for the response. It is optional when the request instead uses a reusable prompt or continues a stored response with previous_response_id.
Each item is an object with a type. Common types are:
message: A conversation message with role and contentfunction_call: A function call requestfunction_call_output: Output from a function callreasoning: A thinking item from an earlier response. Send it back unchanged
Other item types depend on the selected model.
For multimodal input, message.content can be either a plain string or an array of content blocks. For image-capable models, pass images as input_image blocks instead of embedding URLs or Base64 strings directly into plain text.
Example content blocks:
{ "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,..." }
System instructions for the model (equivalent to system message).
Maximum number of tokens to generate.
Sampling temperature. Supported values and defaults depend on the selected model.
Tools the model may call. Supported types and combinations depend on the selected model.
falseIf true, returns a stream of events. See Streaming.
ID of a previous response to continue the conversation from. The response must belong to your account and still be stored; otherwise the request returns 404 with code response_not_found. Continue with the model that produced it. If the service that produced the response is temporarily unavailable, the request can return 503.
trueWhether to store the response for later retrieval and for previous_response_id. With false, TokenLab does not keep the response, and GET /v1/responses/{id} cannot return it.
falseRequest asynchronous execution. Support depends on the selected model. The create call returns at once, usually with status queued or in_progress. Poll Retrieve a response until status is completed, incomplete, failed, or cancelled. A background request can return 503 while background processing is temporarily unavailable.
Tool choice policy, such as auto, none, required, or an object that names one tool. Supported values depend on the selected model.
Additional output sections to return, when the selected model supports them.
Streaming options. include_obfuscation is forwarded where the selected model supports it.
Truncation strategy for long conversations, when the selected model supports it.
TokenLab serves and bills Responses requests at the standard service tier. auto and default are accepted. Other values, such as flex or priority, are removed from the request, and the request is billed at the standard price.
Reference to a reusable prompt template and variables.
Custom metadata stored with the response.
Text output settings. Support for text.format depends on the selected model.
Whether to allow multiple tool calls in parallel, when supported by the selected model.
Nucleus sampling parameter (0-1).
Reasoning options, including effort, depend on the selected model.
Response
Unique identifier for the response.
Always response.
Unix timestamp of when the response was created.
Response state: queued, in_progress, completed, incomplete, failed, or cancelled. Check this field even when the HTTP request succeeds.
List of output items generated by the model.
Token usage statistics.
Related Endpoints
GET /v1/responses/{id}retrieves a stored response.DELETE /v1/responses/{id}deletes a stored response. It does not cancel generation.POST /v1/responses/compactcompacts a conversation and returns aresponse.compactionobject.wss://api.tokenlab.sh/v1/responsescreates responses over WebSocket. See Streaming.- Cancel, input-items, and input-tokens endpoints are not currently available.
Request
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
}'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)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);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
$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']);Vision Input Example
Use image-capable models by placing images inside message.content as input_image blocks. The image_url value can be either a public URL or a Base64 data URL.
{
"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..."
}
]
}
]
}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
}
}Errors
Errors use the OpenAI-style error object. Common cases: 400 for an invalid field or a model without the Responses format, 401 for an invalid key, 402 for insufficient balance, 404 for an unknown previous_response_id, 429 for the rate limit, and 503 when the model cannot serve the request now. See Handle API errors.
Authorization
BearerAuth API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Headers
Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.
Value in
- "auto"
- "verified"
- "official"
Optional key that stops a second run of the same request. Send a new unique value, such as a UUID, for each request, and keep it for retries after a timeout. A retry with the same key does not run again: it returns 409 with idempotency_replay_unavailable, or usually idempotency_conflict when the body changed. Exception: when a non-stream result finished after the client disconnected, a retry with the same key and body within 24 hours returns that result (up to 1 MB) with the header Idempotent-Replayed: true and no second charge. A key longer than 255 characters is ignored, and the request then has no idempotency protection. With background: true, a retry with the same key and body returns the original response object instead and does not create or charge a second response; a different body is rejected, and its status code is not guaranteed. See Retry safely with an idempotency key.
1 <= length <= 255Request Body
application/json
Response
application/json
application/json
application/json
application/json
application/json