TokenLab

Text

Create Response

Creates a response using the OpenAI Responses API format

POST
/v1/responses

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

modelstringrequired

ID of the model to use. See Models for available options.

inputstring | array

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 content
  • function_call: A function call request
  • function_call_output: Output from a function call
  • reasoning: 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,..." }
instructionsstring

System instructions for the model (equivalent to system message).

max_output_tokensinteger

Maximum number of tokens to generate.

temperaturenumber

Sampling temperature. Supported values and defaults depend on the selected model.

toolsarray

Tools the model may call. Supported types and combinations depend on the selected model.

streambooleandefault: false

If true, returns a stream of events. See Streaming.

previous_response_idstring

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.

storebooleandefault: true

Whether 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.

backgroundbooleandefault: false

Request 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_choicestring | object

Tool choice policy, such as auto, none, required, or an object that names one tool. Supported values depend on the selected model.

includearray

Additional output sections to return, when the selected model supports them.

stream_optionsobject

Streaming options. include_obfuscation is forwarded where the selected model supports it.

truncationstring

Truncation strategy for long conversations, when the selected model supports it.

service_tierstring

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.

promptobject

Reference to a reusable prompt template and variables.

metadataobject

Custom metadata stored with the response.

textobject

Text output settings. Support for text.format depends on the selected model.

parallel_tool_callsboolean

Whether to allow multiple tool calls in parallel, when supported by the selected model.

top_pnumber

Nucleus sampling parameter (0-1).

reasoningobject

Reasoning options, including effort, depend on the selected model.

Response

idstring

Unique identifier for the response.

objectstring

Always response.

created_atinteger

Unix timestamp of when the response was created.

statusstring

Response state: queued, in_progress, completed, incomplete, failed, or cancelled. Check this field even when the HTTP request succeeds.

outputarray

List of output items generated by the model.

usageobject

Token usage statistics.

Request

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']);

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

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
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Headers

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

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.

Length1 <= length <= 255

Request Body

application/json

Response

application/json

application/json

application/json

application/json

application/json