# Basic Usage

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:

{% tabs %}
{% tab title="TypeScript" %}

```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);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.post(
    'https://llm.onerouter.pro/v1/responses',
    headers={
        'Authorization': 'Bearer <<API_KEY>>',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'o4-mini',
        'input': 'What is the meaning of life?',
        'max_output_tokens': 9000,
    }
)

result = response.json()
print(result)
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -X POST https://llm.onerouter.pro/v1/responses \
  -H "Authorization: Bearer <<API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "o4-mini",
    "input": "What is the meaning of life?",
    "max_output_tokens": 9000
  }'
```

{% endtab %}
{% endtabs %}

## Structured Message Input

For more complex conversations, use the message array format:

{% tabs %}
{% tab title="TypeScript" %}

```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();
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

result = response.json()
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -X POST https://llm.onerouter.pro/v1/responses \
  -H "Authorization: Bearer <<API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "o4-mini",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Tell me a joke about programming"
          }
        ]
      }
    ],
    "max_output_tokens": 9000
  }'
```

{% endtab %}
{% endtabs %}

## Response Format

The API returns a structured response with the generated content:

```json
{
  '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:

{% tabs %}
{% tab title="TypeScript" %}

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

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

response = requests.post(
    'https://llm.onerouter.pro/v1/responses',
    headers={
        'Authorization': 'Bearer <<API_KEY>>',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'o4-mini',
        'input': 'Write a short story about AI',
        'stream': True,
        'max_output_tokens': 9000,
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        line_str = line.decode('utf-8')
        if line_str.startswith('data: '):
            data = line_str[6:]
            if data == '[DONE]':
                break
            try:
                parsed = json.loads(data)
                print(parsed)
            except json.JSONDecodeError:
                continue
```

{% endtab %}
{% endtabs %}

## 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:

{% tabs %}
{% tab title="TypeScript" %}

```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);
}
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

try:
    response = requests.post(
        'https://llm.onerouter.pro/v1/responses',
        headers={
            'Authorization': 'Bearer <<API_KEY>>',
            'Content-Type': 'application/json',
        },
        json={
            'model': 'o4-mini',
            'input': 'Hello, world!',
        }
    )

    if response.status_code != 200:
        error = response.json()
        print(f"API Error: {error['error']['message']}")
    else:
        result = response.json()
        print(result)

except requests.RequestException as e:
    print(f"Network Error: {e}")
```

{% endtab %}
{% endtabs %}

## Multiple Turn Conversations

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

{% tabs %}
{% tab title="TypeScript" %}

```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();
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

# First request
first_response = requests.post(
    'https://llm.onerouter.pro/v1/responses',
    headers={
        'Authorization': 'Bearer <<API_KEY>>',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'o4-mini',
        'input': [
            {
                'type': 'message',
                'role': 'user',
                'content': [
                    {
                        'type': 'input_text',
                        'text': 'What is the capital of France?',
                    },
                ],
            },
        ],
        'max_output_tokens': 9000,
    }
)

first_result = first_response.json()

# Second request - include previous conversation
second_response = requests.post(
    'https://llm.onerouter.pro/v1/responses',
    headers={
        'Authorization': 'Bearer <<API_KEY>>',
        'Content-Type': 'application/json',
    },
    json={
        '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,
    }
)

second_result = second_response.json()
```

{% endtab %}
{% endtabs %}

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

{% content-ref url="/pages/XFx3c0UJoO1WUH1w30SO" %}
[Reasoning](/docs/api-reference/openai-responses-api/reasoning.md)
{% endcontent-ref %}

* Explore Tool Calling functionality

{% content-ref url="/pages/kUrIIzNBixGVK38m5eIR" %}
[Tool Calling](/docs/api-reference/openai-responses-api/tool-calling.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://infronai.gitbook.io/docs/api-reference/openai-responses-api/basic-usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.