Responses API — TokSpan Docs

Endpoint

http
POST https://api.tokspan.com/v1/responses

Quick Examples

The Responses API follows the same OpenAI SDK patterns — just change the method name:

from openai import OpenAI

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

response = client.responses.create(
    model="MODEL_NAME",
    input="What is the capital of France?",
)

print(response.output_text)

shell
curl -X POST "https://api.tokspan.com/v1/responses" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "input": "What is the capital of France?"
  }'

json — Response
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1700000000,
  "status": "completed",
  "model": "MODEL_NAME",
  "output": [{
    "type": "message",
    "role": "assistant",
    "content": [{
      "type": "output_text",
      "text": "The capital of France is Paris.",
      "annotations": []
    }]
  }],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 8,
    "total_tokens": 20
  }
}

Request Body

Parameter	Type	Required	Description
model	string	Yes	Model ID (e.g., `gpt-4o`, `claude-opus-4-8`). See Models for the full catalog.
input	string / array	Yes	The input for the response. Can be a plain string or an array of message items (e.g., `input_text`, `input_image`).
instructions	string	No	System-level instructions for the model — the Responses API equivalent of a <code>system</code> message.
max_output_tokens	integer	No	Maximum tokens to generate in the response.
temperature	number	No	Sampling temperature (0–2). Higher = more random.
stream	boolean	No	Enable SSE streaming. Default: `false`.
tools	array	No	Tools the model can call, including built-in tools like `web_search_preview` and `file_search`.
tool_choice	string / object	No	Control tool selection: `"auto"`, `"none"`, `"required"`, or a specific tool object.
previous_response_id	string	No	Pass the previous response's `id` to continue a multi-turn conversation with state.
reasoning	object	No	Reasoning configuration for reasoning models (e.g., <code>effort</code>: <code>"low"</code> \| <code>"medium"</code> \| <code>"high"</code>).

Streaming (SSE)

Set stream: true to receive the response incrementally via Server-Sent Events — same as Chat Completions streaming.

shell
curl -X POST "https://api.tokspan.com/v1/responses" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "input": "Tell me a story.",
    "stream": true
  }'

Built-in Tools

The Responses API supports built-in tools that don't require custom function definitions:

Web Search

json
{
  "model": "MODEL_NAME",
  "input": "What is the latest news about AI?",
  "tools": [{
    "type": "web_search_preview"
  }]
}

File Search

json
{
  "model": "MODEL_NAME",
  "input": "Summarize the Q3 report",
  "tools": [{
    "type": "file_search",
    "vector_store_ids": ["vs_abc123"]
  }]
}

Built-in tool availability: Web search and file search require upstream models and channels that support them. Availability depends on the configured channels in your backend.