---
title: "Create response"
method: POST
path: "/v1/responses"
---

# Create response

`POST /v1/responses`

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

## Headers

- `x-api-key` string

## Request body

- ResponsesRequest
  - `model` string, required — 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`).
  - `input` union, required — Text, image, or file inputs to the model. Either a plain string or an array of typed input items.
    - string
    - ResponsesInputItem[]
      - `type` 'message' | 'reasoning' | 'function_call' | 'function_call_output'
      - `role` 'user' | 'assistant' | 'system' | 'developer' — For `type=message`: the role of the message author.
      - `content` union — For `type=message`: a string or an array of typed content objects.
        - string
        - ResponsesInputContent[]
          - `type` 'input_text' | 'input_image' | 'input_file', required
          - `text` string — For `type=input_text`: the text content.
          - `image_url` string — For `type=input_image`: an https:// URL or `data:` URL.
          - `detail` 'low' | 'high' | 'auto' — For `type=input_image`: image fidelity.
          - `filename` string — For `type=input_file`: name of the file.
          - `file_data` string — For `type=input_file`: base64 data URL, e.g. `data:application/pdf;base64,...`.
          - `file_url` string — For `type=input_file`: remote URL of the file.
          - `mime_type` string — For `type=input_file`: optional MIME type override.
      - `name` string — For `type=function_call`: the function name.
      - `arguments` string — For `type=function_call`: JSON-encoded arguments string.
      - `call_id` string — For `type=function_call` and `function_call_output`: identifier linking call and result.
      - `output` string — For `type=function_call_output`: the result returned to the model.
  - `instructions` string — Inserts a system (or developer) message as the first item in the model's context.
  - `max_output_tokens` integer — Upper bound for the number of tokens that can be generated, including visible output tokens and reasoning tokens.
  - `stream` boolean — If true, the response is streamed to the client as it is generated using server-sent events.
  - `temperature` number — Sampling temperature between 0 and 2. Higher values produce more random output.
  - `top_p` number — Nucleus sampling: consider tokens with cumulative probability mass up to top_p.
  - `parallel_tool_calls` boolean — Whether to allow the model to run tool calls in parallel.
  - `tool_choice` union — Controls which (if any) tool is called by the model.
    - 'auto' | 'none' | 'required'
    - object
  - `tools` ResponsesTool[] — Tools the model may call.
    - `type` 'function' | 'web_search', required
    - `name` string — For `type=function`: the function name.
    - `description` string — For `type=function`: a description of when to call the function.
    - `parameters` object — For `type=function`: JSON Schema describing the arguments.
    - `strict` boolean — For `type=function`: when true, the model must produce arguments that exactly match the schema.
  - `reasoning` ResponsesReasoning — Reasoning configuration for reasoning-capable models.
    - `effort` 'low' | 'medium' | 'high' — How much effort the model should spend on reasoning. Defaults to medium.
    - `summary` 'auto' | 'concise' | 'detailed' — Whether and how to summarize the reasoning trace.
  - `text` ResponsesText — Output text configuration, including structured output format.
    - `format` object — Configure the format that the model must output. Set `{ "type": "json_schema" }` for strict structured outputs, or `{ "type": "text" }` (default) for plain text.
      - `type` 'text' | 'json_object' | 'json_schema'
      - `name` string — For `type=json_schema`: schema name.
      - `strict` boolean — For `type=json_schema`: enforce strict schema validation.
      - `schema` object — For `type=json_schema`: the JSON Schema document.
  - `include` string[] — Specify additional output data to include in the model response.
  - `metadata` object — Set of key-value pairs that can be attached to the request.
  - `store` boolean — Whether to store the generated model response for later retrieval via API.
  - `truncation` string — The truncation strategy to use for the model response.
  - `user` string — A unique identifier representing your end-user.

## Response `200`

Response

- ResponsesResponse
  - `id` string, required — Unique identifier for this response.
  - `object` 'response', required — Object type.
  - `created_at` integer, required — Unix timestamp (in seconds) of when the response was created.
  - `model` string, required — Model ID used to generate the response.
  - `status` 'completed' | 'failed' | 'in_progress' | 'incomplete', required — Status of the response generation.
  - `output` ResponsesOutputItem[], required — Output items from the model. Typically one or more `message`, `function_call`, or `reasoning` items.
    - `type` 'message' | 'reasoning' | 'function_call' | 'web_search_call', required
    - `id` string
    - `status` 'in_progress' | 'completed'
    - `role` 'assistant' — For `type=message`.
    - `content` ResponsesOutputContent[] — For `type=message`: model-generated content blocks.
      - `type` 'output_text' | 'output_refusal', required
      - `text` string — For `type=output_text`: the generated text.
      - `refusal` string — For `type=output_refusal`: the refusal message.
    - `summary` unknown[] — For `type=reasoning`: optional summary of the reasoning trace.
      - unknown
    - `encrypted_content` string — For `type=reasoning`: opaque token that can be replayed on subsequent turns.
    - `name` string — For `type=function_call`: the function name.
    - `arguments` string — For `type=function_call`: JSON-encoded arguments string.
    - `call_id` string — For `type=function_call`: identifier to pair with a `function_call_output`.
  - `incomplete_details` object
    - `reason` string — Why the response is incomplete.
  - `error` object
    - `code` string
    - `message` string
  - `usage` ResponsesUsage
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `total_tokens` integer, required
    - `input_tokens_details` object
      - `cached_tokens` integer
    - `output_tokens_details` object
      - `reasoning_tokens` integer
    - `cost` number, float — 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`.

## Other responses

- `400` — Bad request - malformed payload or invalid parameters.
- `401` — Unauthorized - missing or empty Authorization header.
- `402` — Payment required - organization balance exhausted.
- `403` — Forbidden - invalid token or model not in access list.
- `404` — Not found - provider/model not supported.
- `429` — Rate limit exceeded. Retry after the Retry-After header value.
- `500` — Internal server error.
- `502` — Bad gateway - upstream provider returned an invalid response.

---

[API](https://skmtc.dev/requesty/apis/requesty-api.md) · [All operations](https://skmtc.dev/requesty/apis/requesty-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/requesty/requesty-api/revisions/63bc7d99ccde/schema)