Apertis Docs

Text Generation

Responses API

Updated
Reading time
5 min
Edit this page

On this page
POST /v1/responses

The Responses API is compatible with OpenAI's Responses API format, providing a streamlined interface for generating AI responses. This endpoint accepts the input field (instead of messages) and automatically converts it to the internal format.

HTTP Request

cURL

curl https://api.apertis.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APERTIS_API_KEY>" \
    -d '{
        "model": "gpt-5.2",
        "input": "What is the capital of France?"
    }'

Python

from openai import OpenAI

client = OpenAI(
    api_key="<APERTIS_API_KEY>",
    base_url="https://api.apertis.ai/v1"
)

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

print(response.output_text)

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: '<APERTIS_API_KEY>',
  baseURL: 'https://api.apertis.ai/v1'
});

const response = await client.responses.create({
  model: 'gpt-5.2',
  input: 'What is the capital of France?'
});

console.log(response.output_text);

Authentication

Header Format Example
Authorization Bearer token Authorization: Bearer sk-your-api-key

Parameters

Required Parameters

Parameter Type Description
model string The model to use for generating the response
input string/array The input text or array of message objects

Optional Parameters

Parameter Type Description
instructions string High-level instructions for model behavior
stream boolean Enable streaming responses. Default: false
temperature number Sampling temperature (0-2). Default: 1
max_tokens integer Maximum tokens in the response
max_output_tokens integer Upper bound for tokens including reasoning tokens
tools array List of tools the model can use (including web search)
tool_choice string/object Controls tool selection behavior
max_tool_calls integer Maximum number of tool calls allowed
parallel_tool_calls boolean Whether to allow parallel tool execution
reasoning object Reasoning configuration (see below)
text object Text output configuration (see below)
store boolean Whether to store the response for state management
previous_response_id string ID of previous response for multi-turn conversations
truncation string Context overflow handling (e.g., "auto")
metadata object Request metadata (up to 16 key-value pairs)

Reasoning Parameter

The reasoning parameter configures the model's reasoning behavior:

Option Type Description
effort string Reasoning effort level: low, medium, high
summary string Summary style: auto, concise, detailed

cURL

curl https://api.apertis.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APERTIS_API_KEY>" \
    -d '{
        "model": "gpt-5.2",
        "input": "Solve this complex math problem...",
        "reasoning": {"effort": "high", "summary": "detailed"}
    }'

Python

response = client.responses.create(
    model="gpt-5.2",
    input="Solve this complex math problem...",
    reasoning={
        "effort": "high",
        "summary": "detailed"
    }
)

JavaScript

const response = await client.responses.create({
  model: 'gpt-5.2',
  input: 'Solve this complex math problem...',
  reasoning: {
    effort: 'high',
    summary: 'detailed'
  }
});

Text Parameter

The text parameter configures text output:

Option Type Description
format object Output format configuration (e.g., {"type": "json_object"})
verbosity string Output verbosity: concise, normal, verbose

Input Formats

String Input (simple query):

{
  "model": "gpt-5.5",
  "input": "What is the capital of France?"
}

Array Input (conversation):

{
  "model": "gpt-5.5",
  "input": [
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hi there!"},
    {"role": "user", "content": "What's 2+2?"}
  ]
}

Example Usage

Python

from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.5",
    input="Explain quantum computing in simple terms."
)

print(response.output_text)

JavaScript

import OpenAI from 'openai';

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

const response = await client.responses.create({
  model: 'gpt-5.5',
  input: 'Explain quantum computing in simple terms.'
});

console.log(response.output_text);

Use the tools parameter to enable web search:

cURL

curl https://api.apertis.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APERTIS_API_KEY>" \
    -d '{
        "model": "gpt-5.2",
        "input": "What are the latest news about AI?",
        "tools": [{"type": "web_search_preview"}]
    }'

Python

response = client.responses.create(
    model="gpt-5.2",
    input="What are the latest news about AI?",
    tools=[{"type": "web_search_preview"}]
)

JavaScript

const response = await client.responses.create({
  model: 'gpt-5.2',
  input: 'What are the latest news about AI?',
  tools: [{ type: 'web_search_preview' }]
});

With Reasoning

cURL

curl https://api.apertis.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APERTIS_API_KEY>" \
    -d '{
        "model": "gpt-5.2",
        "input": "Prove the Pythagorean theorem step by step.",
        "reasoning": {"effort": "high", "summary": "detailed"}
    }'

Python

response = client.responses.create(
    model="gpt-5.2",
    input="Prove the Pythagorean theorem step by step.",
    reasoning={
        "effort": "high",
        "summary": "detailed"
    }
)

JavaScript

const response = await client.responses.create({
  model: 'gpt-5.2',
  input: 'Prove the Pythagorean theorem step by step.',
  reasoning: {
    effort: 'high',
    summary: 'detailed'
  }
});

Streaming

cURL

curl https://api.apertis.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APERTIS_API_KEY>" \
    -d '{
        "model": "gpt-5.2",
        "input": "Write a short story about a robot.",
        "stream": true
    }'

Python

stream = client.responses.create(
    model="gpt-5.2",
    input="Write a short story about a robot.",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

JavaScript

const stream = await client.responses.create({
  model: 'gpt-5.2',
  input: 'Write a short story about a robot.',
  stream: true
});

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') process.stdout.write(event.delta);
}

Multi-turn Conversation

cURL

curl https://api.apertis.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APERTIS_API_KEY>" \
    -d '{
        "model": "gpt-5.2",
        "input": [
            {"role": "user", "content": "What is Python?"},
            {"role": "assistant", "content": "Python is a high-level programming language..."},
            {"role": "user", "content": "How do I install it?"}
        ]
    }'

Python

response = client.responses.create(
    model="gpt-5.2",
    input=[
        {"role": "user", "content": "What is Python?"},
        {"role": "assistant", "content": "Python is a high-level programming language..."},
        {"role": "user", "content": "How do I install it?"}
    ]
)

JavaScript

const response = await client.responses.create({
  model: 'gpt-5.2',
  input: [
    { role: 'user', content: 'What is Python?' },
    { role: 'assistant', content: 'Python is a high-level programming language...' },
    { role: 'user', content: 'How do I install it?' }
  ]
});

With Instructions

Use instructions to provide high-level guidance for model behavior:

cURL

curl https://api.apertis.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APERTIS_API_KEY>" \
    -d '{
        "model": "gpt-5.2",
        "instructions": "You are a helpful coding assistant. Always provide code examples.",
        "input": "How do I read a file in Python?"
    }'

Python

response = client.responses.create(
    model="gpt-5.2",
    instructions="You are a helpful coding assistant. Always provide code examples.",
    input="How do I read a file in Python?"
)

JavaScript

const response = await client.responses.create({
  model: 'gpt-5.2',
  instructions: 'You are a helpful coding assistant. Always provide code examples.',
  input: 'How do I read a file in Python?'
});

Stateful Conversations

Use store and previous_response_id for multi-turn conversations with state:

cURL

curl https://api.apertis.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APERTIS_API_KEY>" \
    -d '{
        "model": "gpt-5.2",
        "input": "My name is Alice.",
        "store": true
    }'

# Follow-up request - reference the previous response
curl https://api.apertis.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APERTIS_API_KEY>" \
    -d '{
        "model": "gpt-5.2",
        "input": "What is my name?",
        "previous_response_id": "<RESPONSE_ID>"
    }'

Python

# First request - store the response
response1 = client.responses.create(
    model="gpt-5.2",
    input="My name is Alice.",
    store=True
)

# Follow-up request - reference the previous response
response2 = client.responses.create(
    model="gpt-5.2",
    input="What's my name?",
    previous_response_id=response1.id
)

JavaScript

// First request - store the response
const response1 = await client.responses.create({
  model: 'gpt-5.2',
  input: 'My name is Alice.',
  store: true
});

// Follow-up request - reference the previous response
const response2 = await client.responses.create({
  model: 'gpt-5.2',
  input: "What's my name?",
  previous_response_id: response1.id
});

With Function Calling

cURL

curl https://api.apertis.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APERTIS_API_KEY>" \
    -d '{
        "model": "gpt-5.2",
        "input": "What is the weather in Tokyo?",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "Get the current weather",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "location": {"type": "string"}
                        },
                        "required": ["location"]
                    }
                }
            }
        ],
        "tool_choice": "auto"
    }'

Python

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    }
]

response = client.responses.create(
    model="gpt-5.2",
    input="What's the weather in Tokyo?",
    tools=tools,
    tool_choice="auto"
)

JavaScript

const tools = [
  {
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get the current weather',
      parameters: {
        type: 'object',
        properties: {
          location: { type: 'string' }
        },
        required: ['location']
      }
    }
  }
];

const response = await client.responses.create({
  model: 'gpt-5.2',
  input: "What's the weather in Tokyo?",
  tools,
  tool_choice: 'auto'
});

Response Format

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1699000000,
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The capital of France is Paris."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 8,
    "total_tokens": 20
  }
}

Supported Models

All chat models available through Apertis are supported with the Responses API. The API intelligently routes requests based on model capabilities:

Models with Native /v1/responses Support

These models natively support the Responses API format on upstream providers:

Model Series Examples
o1 Series o1-pro
o3 Series o3-mini-high, o3-deep-research
o4 Series o4-mini-high, o4-mini-deep-research
GPT-5 Series gpt-5.1, gpt-5.2, gpt-5.5, gpt-5-*
Codex Models gpt-5-codex, gpt-5-codex-*

Responses-Only Models

Some advanced models only support the /v1/responses endpoint and cannot be used with /v1/chat/completions or /v1/messages:

Model Description
gpt-5-pro GPT-5 Pro variant
gpt-5-codex-* GPT-5 Codex variants
o1-pro O1 Pro
codex-mini Codex Mini

All Other Models

For models that don't natively support /v1/responses (like Claude, Gemini, GPT-4o, etc.), Apertis automatically:

  1. Routes the request via /v1/chat/completions internally
  2. Converts the response back to Responses API format
  3. Returns the response in the expected format

This means you can use any model with the Responses API - the conversion is handled transparently.

Provider Example Models Native Support
Anthropic claude-sonnet-4-6, claude-opus-4-8 Via fallback
Google gemini-3.1-pro-preview, gemini-3-flash-preview Via fallback
Meta llama-3.1-70b-instruct, llama-3.1-8b-instruct Via fallback
xAI grok-4.3, grok-4.5 Via fallback

Differences from Chat Completions

Feature Responses API Chat Completions
Input field input messages
String input Supported Not supported
Instructions instructions parameter System message in messages
Reasoning config reasoning object reasoning_effort string
Text config text object Not available
State management store, previous_response_id Manual message array
Token limit max_output_tokens max_tokens
Tool call limits max_tool_calls Not available
Truncation truncation parameter Not available

Context Compression

The Responses API supports context compression to automatically reduce token usage for long conversations. Enable it via the request body or HTTP headers:

cURL

curl https://api.apertis.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <APERTIS_API_KEY>" \
    -d '{
        "model": "gpt-5.2",
        "input": [
            {"role": "user", "content": "Explain distributed systems"},
            {"role": "assistant", "content": "Distributed systems are..."},
            {"role": "user", "content": "Summarize the key points"}
        ],
        "compression": {"enabled": true, "strategy": "on", "model": "gemini-3-flash-preview"}
    }'

Python

response = client.responses.create(
    model="gpt-5.2",
    input=[
        {"role": "user", "content": "Explain distributed systems"},
        {"role": "assistant", "content": "Distributed systems are..."},
        # ... long conversation history ...
        {"role": "user", "content": "Summarize the key points"}
    ],
    extra_body={
        "compression": {
            "enabled": True,
            "strategy": "on",
            "model": "gemini-3-flash-preview"
        }
    }
)

JavaScript

const response = await client.responses.create({
  model: 'gpt-5.2',
  input: [
    { role: 'user', content: 'Explain distributed systems' },
    { role: 'assistant', content: 'Distributed systems are...' },
    // ... long conversation history ...
    { role: 'user', content: 'Summarize the key points' }
  ],
  compression: {
    enabled: true,
    strategy: 'on',
    model: 'gemini-3-flash-preview'
  }
});

See Context Compression for full configuration options and strategies.