> ## Documentation Index
> Fetch the complete documentation index at: https://docs.requesty.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Response

> Send input to an OpenAI-compatible model using the Responses API format and receive a response.

<RequestExample>
  ```bash cURL theme={"dark"}
  curl https://router.requesty.ai/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_REQUESTY_API_KEY" \
    -d '{
      "model": "openai-responses/gpt-5",
      "input": "Tell me a three sentence bedtime story about a unicorn."
    }'
  ```

  ```python Python theme={"dark"}
  from openai import OpenAI

  client = OpenAI(
      api_key="YOUR_REQUESTY_API_KEY",
      base_url="https://router.requesty.ai/v1",
  )

  response = client.responses.create(
      model="openai-responses/gpt-5",
      input="Tell me a three sentence bedtime story about a unicorn.",
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={"dark"}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.REQUESTY_API_KEY,
    baseURL: "https://router.requesty.ai/v1",
  });

  const response = await client.responses.create({
    model: "openai-responses/gpt-5",
    input: "Tell me a three sentence bedtime story about a unicorn.",
  });

  console.log(response.output_text);
  ```
</RequestExample>

<ResponseExample>
  ```json Response 200 theme={"dark"}
  {
    "id": "resp_abc123",
    "object": "response",
    "created_at": 1748200000,
    "model": "openai-responses/gpt-5",
    "output": [
      {
        "type": "message",
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "Once upon a time, a tiny unicorn named Sparkle discovered a rainbow bridge leading to a hidden meadow. She danced under the stars with fireflies until the moon sang her a lullaby. And every night after, Sparkle dreamed of adventures yet to come."
          }
        ]
      }
    ],
    "usage": {
      "input_tokens": 15,
      "output_tokens": 58,
      "total_tokens": 73
    }
  }
  ```
</ResponseExample>

Send input to an OpenAI-compatible model and receive a response. This endpoint follows the OpenAI Responses API format and supports all OpenAI models that expose the Responses API natively, as well as compatible models from other providers through Requesty's routing.

## Base URL

```
https://router.requesty.ai/v1/responses
```

## Authentication

The Responses endpoint accepts either OpenAI-style bearer auth or Anthropic-style `x-api-key` auth. Use whichever your client library expects.

```bash theme={"dark"}
Authorization: Bearer YOUR_REQUESTY_API_KEY
```

```bash theme={"dark"}
x-api-key: YOUR_REQUESTY_API_KEY
```

## Headers

| Header          | Required | Description                         |
| --------------- | -------- | ----------------------------------- |
| `Authorization` | ✅ \*     | Bearer token with your Requesty key |
| `x-api-key`     | ✅ \*     | Your Requesty API key (alternative) |
| `Content-Type`  | ✅        | Must be `application/json`          |

\* Provide one of `Authorization` or `x-api-key`.

## Example Request

```bash theme={"dark"}
curl https://router.requesty.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_REQUESTY_API_KEY" \
  -d '{
    "model": "openai-responses/gpt-5",
    "input": "Tell me a three sentence bedtime story about a unicorn."
  }'
```

## Using the OpenAI SDK

The Responses endpoint is fully compatible with the official OpenAI SDK. Just point `base_url` at Requesty:

```python theme={"dark"}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_REQUESTY_API_KEY",
    base_url="https://router.requesty.ai/v1",
)

response = client.responses.create(
    model="openai-responses/gpt-5",
    input="Tell me a three sentence bedtime story about a unicorn.",
)

print(response.output_text)
```

## Model Selection

You can use any model available in the [Model Library](https://app.requesty.ai/model-list). Requesty translates the request shape for non-OpenAI providers automatically.

* **OpenAI Models:** `openai-responses/gpt-5`, `openai-responses/gpt-5-mini`, `openai-responses/gpt-4.1`, `openai-responses/gpt-4o`
* **Anthropic Models:** `anthropic/claude-sonnet-4-5`, `anthropic/claude-opus-4`
* **Google Models:** `google/gemini-2.5-pro`, `google/gemini-2.5-flash`
* **Other Providers:** `mistral/mistral-large-2411`, `meta/llama-3.3-70b-instruct`

<Info>
  To route OpenAI models through their native Responses API (required for full feature parity, including file inputs and the `response.*` event stream), use the `openai-responses/` prefix. The standard `openai/` prefix routes through Chat Completions under the hood.
</Info>

<Info>
  While this endpoint uses the OpenAI Responses format, Requesty automatically handles format conversion for non-OpenAI providers, so you can
  use any supported model with this endpoint.
</Info>

## Input Formats

The `input` field accepts either a plain string or an array of input items. Use the array form for multi-turn conversations, tool results, and rich content.

### String input

```json theme={"dark"}
{
	"model": "openai-responses/gpt-5",
	"input": "Write a haiku about routers."
}
```

### Multi-turn input

```json theme={"dark"}
{
	"model": "openai-responses/gpt-5",
	"input": [
		{ "role": "user", "content": "Hi, my name is John." },
		{ "role": "assistant", "content": "Hello John, nice to meet you." },
		{ "role": "user", "content": "What is my name?" }
	]
}
```

## Instructions

Use the `instructions` parameter to set a system-level prompt that applies to the entire request. It is equivalent to a system or developer message at the start of the conversation.

```json theme={"dark"}
{
	"model": "openai-responses/gpt-5",
	"instructions": "You are a helpful assistant that always responds in JSON.",
	"input": "Summarize the weather in Paris today."
}
```

## Streaming

Enable streaming by setting `stream: true`. The response is delivered as Server-Sent Events using the OpenAI Responses event format (`response.created`, `response.output_text.delta`, `response.completed`, etc.).

```json theme={"dark"}
{
	"model": "openai-responses/gpt-5",
	"input": "Write a short story.",
	"stream": true
}
```

To receive a final `usage` block with cost on streaming requests, no additional parameter is required. The `response.completed` event includes the full `usage` object.

## Vision Support

Send images using the `input_image` content type. You can pass an image URL or a base64 data URL.

```json theme={"dark"}
{
	"model": "openai-responses/gpt-5",
	"input": [
		{
			"role": "user",
			"content": [
				{ "type": "input_text", "text": "What is in this image?" },
				{
					"type": "input_image",
					"image_url": "https://example.com/image.jpg"
				}
			]
		}
	]
}
```

## PDF Support

Send PDFs using the `input_file` content type. You can provide the PDF as either a base64 data URL or a remote URL.

```json theme={"dark"}
{
	"model": "openai-responses/gpt-5",
	"input": [
		{
			"role": "user",
			"content": [
				{ "type": "input_text", "text": "Summarize this PDF." },
				{
					"type": "input_file",
					"filename": "document.pdf",
					"file_data": "data:application/pdf;base64,<base64-encoded-pdf-data>"
				}
			]
		}
	]
}
```

See the [PDF Support](/features/pdf-support) guide for the full list of supported providers.

## Web Search

Enable real-time web search by adding `{ "type": "web_search" }` to the `tools` array. The response includes `web_search_call` output items and `url_citation` annotations on text content.

```json theme={"dark"}
{
  "model": "openai-responses/gpt-4.1",
  "input": "What are the latest developments in artificial intelligence?",
  "tools": [{ "type": "web_search" }],
  "stream": true
}
```

Works with OpenAI, Anthropic, Vertex/Gemini, xAI, and Perplexity models. See the [Web Search guide](/features/web-search) for response format details and provider-specific behavior.

## Tool Use

Define tools the model may call. The Responses API uses a flatter shape than Chat Completions: `name`, `description`, and `parameters` live at the top level of each tool entry.

```json theme={"dark"}
{
	"model": "openai-responses/gpt-5",
	"input": "What is the weather like in New York?",
	"tools": [
		{
			"type": "function",
			"name": "get_weather",
			"description": "Get the current weather in a given location",
			"parameters": {
				"type": "object",
				"properties": {
					"location": {
						"type": "string",
						"description": "The city and state, e.g. San Francisco, CA"
					}
				},
				"required": ["location"]
			},
			"strict": true
		}
	]
}
```

To return a tool result on the next turn, send a `function_call_output` item in `input`:

```json theme={"dark"}
{
	"model": "openai-responses/gpt-5",
	"input": [
		{
			"type": "function_call",
			"name": "get_weather",
			"call_id": "call_abc123",
			"arguments": "{\"location\": \"New York, NY\"}"
		},
		{
			"type": "function_call_output",
			"call_id": "call_abc123",
			"output": "{\"temperature\": 68, \"conditions\": \"sunny\"}"
		}
	]
}
```

## Reasoning

For reasoning-capable models (e.g. `openai-responses/gpt-5`, `openai-responses/o3`), configure reasoning effort and the optional summary:

```json theme={"dark"}
{
	"model": "openai-responses/gpt-5",
	"input": "Plan a three day trip to Tokyo.",
	"reasoning": {
		"effort": "medium",
		"summary": "auto"
	}
}
```

* `effort`: `low`, `medium`, or `high`. Lower effort produces faster responses with fewer reasoning tokens.
* `summary`: `auto`, `concise`, or `detailed`. Controls whether the model returns a reasoning summary alongside the final answer.

## Structured Outputs

Set `text.format` to enforce JSON-mode or a strict JSON Schema on the output.

```json theme={"dark"}
{
	"model": "openai-responses/gpt-5",
	"input": "Extract entities from: The quick brown fox jumps over the lazy dog.",
	"text": {
		"format": {
			"type": "json_schema",
			"name": "Entities",
			"strict": true,
			"schema": {
				"type": "object",
				"properties": {
					"animals": { "type": "array", "items": { "type": "string" } }
				},
				"required": ["animals"]
			}
		}
	}
}
```

See the [Structured Outputs](/features/structured-outputs) guide for full examples.

## Response Format

A successful response follows the OpenAI Responses format:

```json theme={"dark"}
{
	"id": "resp_01ABC123",
	"object": "response",
	"created_at": 1730000000,
	"model": "openai-responses/gpt-5",
	"status": "completed",
	"output": [
		{
			"id": "msg_01ABC123",
			"type": "message",
			"role": "assistant",
			"status": "completed",
			"content": [
				{
					"type": "output_text",
					"text": "Once upon a time, a unicorn..."
				}
			]
		}
	],
	"usage": {
		"input_tokens": 12,
		"input_tokens_details": { "cached_tokens": 0 },
		"output_tokens": 27,
		"output_tokens_details": { "reasoning_tokens": 0 },
		"total_tokens": 39,
		"cost": 0.000234
	}
}
```

The `cost` field inside `usage` is a Requesty extension and reports the USD cost of the request. It is returned by default on non-streaming responses, and on the final `response.completed` event when streaming. See [Cost Tracking](/features/cost-tracking#per-request-cost-in-the-api-response).

## Error Handling

The API returns standard HTTP status codes:

* `200` - Success
* `400` - Bad Request (invalid parameters)
* `401` - Unauthorized (invalid API key)
* `403` - Forbidden (insufficient permissions)
* `429` - Rate Limited
* `500` - Internal Server Error

## Key Differences from OpenAI Chat Completions

* **`input` instead of `messages`:** Accepts a string or a list of typed items (messages, tool calls, tool results, reasoning).
* **`instructions` instead of system messages:** System prompts are passed via the top-level `instructions` field.
* **Flat tool shape:** Tools declare `name`, `description`, and `parameters` directly, without the nested `function` wrapper.
* **Content types are prefixed:** `input_text`, `input_image`, `input_file` for user inputs; `output_text` and `output_refusal` for model outputs.
* **Event-typed streaming:** Streaming uses named events (`response.created`, `response.output_text.delta`, `response.completed`) rather than choice deltas.
* **`max_output_tokens` instead of `max_tokens`:** Caps the total of visible and reasoning tokens.

<Tip>
  For seamless compatibility with the OpenAI Python and Node SDKs' `responses.create(...)` interface, use this endpoint. For broader
  portability across providers, consider the [Chat Completions endpoint](/api-reference/endpoint/chat-completions-create) instead.
</Tip>


## OpenAPI

````yaml POST /v1/responses
openapi: 3.0.3
info:
  title: Requesty API
  description: Requesty API for AI model routing and key management
  version: 1.0.0
servers:
  - url: https://api-v2.requesty.ai
    description: Management API endpoint
  - url: https://router.requesty.ai
    description: Inference router endpoint
security:
  - BearerAuth: []
paths:
  /v1/responses:
    servers:
      - url: https://router.requesty.ai
        description: Inference router endpoint
    post:
      summary: Create response
      description: >-
        Send input to an OpenAI-compatible model using the Responses API format
        and receive a response.
      operationId: createResponse
      parameters:
        - name: x-api-key
          in: header
          required: false
          schema:
            type: string
          description: >-
            Your Requesty API key. Alternative to the standard `Authorization:
            Bearer` header.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
            example:
              model: openai-responses/gpt-5
              input: Tell me a three sentence bedtime story about a unicorn.
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
              example:
                id: resp_abc123
                object: response
                created_at: 1748200000
                model: openai-responses/gpt-5
                output:
                  - type: message
                    role: assistant
                    content:
                      - type: output_text
                        text: >-
                          Once upon a time, a tiny unicorn named Sparkle
                          discovered a rainbow bridge leading to a hidden
                          meadow. She danced under the stars with fireflies
                          until the moon sang her a lullaby. And every night
                          after, Sparkle dreamed of adventures yet to come.
                usage:
                  input_tokens: 15
                  output_tokens: 58
                  total_tokens: 73
        '400':
          description: Bad request - malformed payload or invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or empty Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required - organization balance exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - invalid token or model not in access list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found - provider/model not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded. Retry after the Retry-After header value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad gateway - upstream provider returned an invalid response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ResponsesRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: >-
            The model to use for the response. To route OpenAI models through
            their native Responses API, use the `openai-responses/` prefix (e.g.
            `openai-responses/gpt-5`).
          default: openai-responses/gpt-5
          example: openai-responses/gpt-5
        input:
          description: >-
            Text, image, or file inputs to the model. Either a plain string or
            an array of typed input items.
          oneOf:
            - type: string
              example: Tell me a three sentence bedtime story about a unicorn.
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesInputItem'
        instructions:
          type: string
          description: >-
            Inserts a system (or developer) message as the first item in the
            model's context.
        max_output_tokens:
          type: integer
          minimum: 1
          description: >-
            Upper bound for the number of tokens that can be generated,
            including visible output tokens and reasoning tokens.
        stream:
          type: boolean
          description: >-
            If true, the response is streamed to the client as it is generated
            using server-sent events.
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: >-
            Sampling temperature between 0 and 2. Higher values produce more
            random output.
        top_p:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Nucleus sampling: consider tokens with cumulative probability mass
            up to top_p.
        parallel_tool_calls:
          type: boolean
          description: Whether to allow the model to run tool calls in parallel.
        tool_choice:
          oneOf:
            - type: string
              enum:
                - auto
                - none
                - required
            - type: object
          description: Controls which (if any) tool is called by the model.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesTool'
          description: Tools the model may call.
        reasoning:
          $ref: '#/components/schemas/ResponsesReasoning'
        text:
          $ref: '#/components/schemas/ResponsesText'
        include:
          type: array
          items:
            type: string
          description: Specify additional output data to include in the model response.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Set of key-value pairs that can be attached to the request.
        store:
          type: boolean
          description: >-
            Whether to store the generated model response for later retrieval
            via API.
        truncation:
          type: string
          description: The truncation strategy to use for the model response.
        user:
          type: string
          description: A unique identifier representing your end-user.
    ResponsesResponse:
      type: object
      required:
        - id
        - object
        - created_at
        - model
        - status
        - output
      properties:
        id:
          type: string
          description: Unique identifier for this response.
        object:
          type: string
          enum:
            - response
          description: Object type.
        created_at:
          type: integer
          description: Unix timestamp (in seconds) of when the response was created.
        model:
          type: string
          description: Model ID used to generate the response.
        status:
          type: string
          enum:
            - completed
            - failed
            - in_progress
            - incomplete
          description: Status of the response generation.
        output:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesOutputItem'
          description: >-
            Output items from the model. Typically one or more `message`,
            `function_call`, or `reasoning` items.
        incomplete_details:
          type: object
          properties:
            reason:
              type: string
              description: Why the response is incomplete.
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
        usage:
          $ref: '#/components/schemas/ResponsesUsage'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - origin
            - message
          properties:
            origin:
              type: string
              enum:
                - router
                - provider
              description: >-
                Whether the error originated from Requesty's router or an
                upstream provider.
            message:
              type: string
              description: Human-readable error description.
    ResponsesInputItem:
      type: object
      description: >-
        Typed input item. Use `type=message` for chat turns, `function_call` to
        replay a tool call, and `function_call_output` to provide a tool result.
      properties:
        type:
          type: string
          enum:
            - message
            - reasoning
            - function_call
            - function_call_output
        role:
          type: string
          enum:
            - user
            - assistant
            - system
            - developer
          description: 'For `type=message`: the role of the message author.'
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesInputContent'
          description: 'For `type=message`: a string or an array of typed content objects.'
        name:
          type: string
          description: 'For `type=function_call`: the function name.'
        arguments:
          type: string
          description: 'For `type=function_call`: JSON-encoded arguments string.'
        call_id:
          type: string
          description: >-
            For `type=function_call` and `function_call_output`: identifier
            linking call and result.
        output:
          type: string
          description: 'For `type=function_call_output`: the result returned to the model.'
    ResponsesTool:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - function
            - web_search
        name:
          type: string
          description: 'For `type=function`: the function name.'
        description:
          type: string
          description: 'For `type=function`: a description of when to call the function.'
        parameters:
          type: object
          description: 'For `type=function`: JSON Schema describing the arguments.'
        strict:
          type: boolean
          description: >-
            For `type=function`: when true, the model must produce arguments
            that exactly match the schema.
    ResponsesReasoning:
      type: object
      description: Reasoning configuration for reasoning-capable models.
      properties:
        effort:
          type: string
          enum:
            - low
            - medium
            - high
          description: >-
            How much effort the model should spend on reasoning. Defaults to
            medium.
        summary:
          type: string
          enum:
            - auto
            - concise
            - detailed
          description: Whether and how to summarize the reasoning trace.
    ResponsesText:
      type: object
      description: Output text configuration, including structured output format.
      properties:
        format:
          type: object
          description: >-
            Configure the format that the model must output. Set `{ "type":
            "json_schema" }` for strict structured outputs, or `{ "type": "text"
            }` (default) for plain text.
          properties:
            type:
              type: string
              enum:
                - text
                - json_object
                - json_schema
            name:
              type: string
              description: 'For `type=json_schema`: schema name.'
            strict:
              type: boolean
              description: 'For `type=json_schema`: enforce strict schema validation.'
            schema:
              type: object
              description: 'For `type=json_schema`: the JSON Schema document.'
    ResponsesOutputItem:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - message
            - reasoning
            - function_call
            - web_search_call
        id:
          type: string
        status:
          type: string
          enum:
            - in_progress
            - completed
        role:
          type: string
          enum:
            - assistant
          description: For `type=message`.
        content:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesOutputContent'
          description: 'For `type=message`: model-generated content blocks.'
        summary:
          type: array
          description: 'For `type=reasoning`: optional summary of the reasoning trace.'
        encrypted_content:
          type: string
          description: >-
            For `type=reasoning`: opaque token that can be replayed on
            subsequent turns.
        name:
          type: string
          description: 'For `type=function_call`: the function name.'
        arguments:
          type: string
          description: 'For `type=function_call`: JSON-encoded arguments string.'
        call_id:
          type: string
          description: >-
            For `type=function_call`: identifier to pair with a
            `function_call_output`.
    ResponsesUsage:
      type: object
      required:
        - input_tokens
        - output_tokens
        - total_tokens
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        total_tokens:
          type: integer
        input_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
        output_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
        cost:
          type: number
          format: float
          description: >-
            Requesty's USD cost for this request. Returned by default on
            non-streaming responses. For streaming, the final
            `response.completed` event includes `usage` with `cost`.
    ResponsesInputContent:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - input_text
            - input_image
            - input_file
        text:
          type: string
          description: 'For `type=input_text`: the text content.'
        image_url:
          type: string
          description: 'For `type=input_image`: an https:// URL or `data:` URL.'
        detail:
          type: string
          enum:
            - low
            - high
            - auto
          description: 'For `type=input_image`: image fidelity.'
        filename:
          type: string
          description: 'For `type=input_file`: name of the file.'
        file_data:
          type: string
          description: >-
            For `type=input_file`: base64 data URL, e.g.
            `data:application/pdf;base64,...`.
        file_url:
          type: string
          description: 'For `type=input_file`: remote URL of the file.'
        mime_type:
          type: string
          description: 'For `type=input_file`: optional MIME type override.'
    ResponsesOutputContent:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - output_text
            - output_refusal
        text:
          type: string
          description: 'For `type=output_text`: the generated text.'
        refusal:
          type: string
          description: 'For `type=output_refusal`: the refusal message.'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````