TokenLab
Get API key
DocumentationAPI ReferenceIntegrations

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. 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 can be:

  • message: A conversation message with role and content
  • function_call: A function call request
  • function_call_output: Output from a function call

For multimodal input, message.content can be either a plain string or an array of content blocks. For image-capable models such as GPT-5.6 Terra variants, 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.

previous_response_idstring

ID of a previous response to continue the conversation from.

storebooleandefault: true

Whether to store the response for later retrieval.

backgroundbooleandefault: false

Request asynchronous execution. Support depends on the selected model.

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_callsbooleandefault: true

Whether to allow multiple tool calls in parallel.

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.

  • GET /v1/responses/{id} retrieves a stored response and supports include, include_obfuscation, stream, and starting_after.
  • DELETE /v1/responses/{id} deletes a stored response. It does not cancel generation.
  • POST /v1/responses/compact returns a response.compaction object.
  • Cancel, input-items, and input-tokens endpoints are not currently available.

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
  }
}

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"

Request Body

application/json

Response

application/json

application/json

application/json

Create Chat Completion

Previous

Create Message

Next