Basic Usage

Getting started with the Responses API

The Responses API supports both simple string input and structured message arrays, making it easy to get started with basic text generation.

Simple String Input

The simplest way to use the API is with a string input:

TypeScript

const response = await fetch('https://llm.onerouter.pro/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <<API_KEY>>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'o4-mini',
    input: 'What is the meaning of life?',
    max_output_tokens: 9000,
  }),
});

const result = await response.json();
console.log(result);

Python

cURL

Structured Message Input

For more complex conversations, use the message array format:

TypeScript

const response = await fetch('https://llm.onerouter.pro/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <<API_KEY>>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'o4-mini',
    input: [
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'Tell me a joke about programming',
          },
        ],
      },
    ],
    max_output_tokens: 9000,
  }),
});

const result = await response.json();

Python

cURL

Response Format

The API returns a structured response with the generated content:

{
  'id': 'resp_01dba0cc1d0017a500691ad2223c48819393303f3018ccd9d2',
  'object': 'response',
  'created_at': 1763365410,
  'status': 'completed',
  'background': False,
  'content_filters': None,
  'error': None,
  'incomplete_details': None,
  'instructions': None,
  'max_output_tokens': 9000,
  'max_tool_calls': None,
  'model': 'o4-mini',
  'output': [{
    'id': 'rs_01dba0cc1d0017a500691ad222e6348193978f00e3bdffedc6',
    'type': 'reasoning',
    'summary': []
  }, {
    'id': 'msg_01dba0cc1d0017a500691ad2248b808193afa1088dc35b886e',
    'type': 'message',
    'status': 'completed',
    'content': [{
      'type': 'output_text',
      'annotations': [],
      'logprobs': [],
      'text': 'Why do programmers prefer dark mode?  \nBecause light attracts bugs!'
    }],
    'role': 'assistant'
  }],
  'parallel_tool_calls': True,
  'previous_response_id': None,
  'prompt_cache_key': None,
  'reasoning': {
    'effort': 'medium',
    'summary': None
  },
  'safety_identifier': None,
  'service_tier': 'auto',
  'store': True,
  'temperature': 1.0,
  'text': {
    'format': {
      'type': 'text'
    },
    'verbosity': 'medium'
  },
  'tool_choice': 'auto',
  'tools': [],
  'top_logprobs': 0,
  'top_p': 1.0,
  'truncation': 'disabled',
  'usage': {
    'input_tokens': 12,
    'input_tokens_details': {
      'cached_tokens': 0
    },
    'output_tokens': 147,
    'output_tokens_details': {
      'reasoning_tokens': 128
    },
    'total_tokens': 159
  },
  'user': None,
  'metadata': {}
}

Streaming Responses

Enable streaming for real-time response generation:

TypeScript

const response = await fetch('https://llm.onerouter.pro/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <<API_KEY>>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'o4-mini',
    input: 'Write a short story about AI',
    stream: true,
    max_output_tokens: 9000,
  }),
});

const reader = response.body?.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6);
      if (data === '[DONE]') return;

      try {
        const parsed = JSON.parse(data);
        console.log(parsed);
      } catch (e) {
        // Skip invalid JSON
      }
    }
  }
}

Python

Common Parameters

Parameter	Type	Description
model	string	Required. Model to use (e.g., o4-mini)
input	string or array	Required. Text or message array
stream	boolean	Enable streaming responses (default: false)
max_output_tokens	integer	Maximum tokens to generate
temperature	number	Sampling temperature (0-2)
top_p	number	Nucleus sampling parameter (0-1)

Error Handling

Handle common errors gracefully:

TypeScript

try {
  const response = await fetch('https://llm.onerouter.pro/v1/responses', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <<API_KEY>>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'o4-mini',
      input: 'Hello, world!',
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error.error.message);
    return;
  }

  const result = await response.json();
  console.log(result);
} catch (error) {
  console.error('Network Error:', error);
}

Python

Multiple Turn Conversations

Since the Responses API is stateless, you must include the full conversation history in each request to maintain context:

TypeScript

// First request
const firstResponse = await fetch('https://llm.onerouter.pro/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <<API_KEY>>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/o4-mini',
    input: [
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'What is the capital of France?',
          },
        ],
      },
    ],
    max_output_tokens: 9000,
  }),
});

const firstResult = await firstResponse.json();

// Second request - include previous conversation
const secondResponse = await fetch('https://llm.onerouter.pro/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <<API_KEY>>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'o4-mini',
    input: [
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'What is the capital of France?',
          },
        ],
      },
      {
        type: 'message',
        role: 'assistant',
        id: 'msg_abc123',
        status: 'completed',
        content: [
          {
            type: 'output_text',
            text: 'The capital of France is Paris.',
            annotations: []
          }
        ]
      },
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'What is the population of that city?',
          },
        ],
      },
    ],
    max_output_tokens: 9000,
  }),
});

const secondResult = await secondResponse.json();

Python

The `id` and `status` fields are required for any `assistant` role messages included in the conversation history. Always include the complete conversation history in each request. The API does not store previous messages, so context must be maintained client-side.

Next Steps

• Learn about Reasoning capabilities

Reasoning

• Explore Tool Calling functionality

Tool Calling