---
title: "Create a response"
method: POST
path: "/responses"
tags: ["responses"]
---

# Create a response

`POST /responses`

Creates a model response using the Responses API. Supports streaming (`stream: true`, server-sent events) and background mode (`background: true`). When streaming, each frame carries a named `event:` and a JSON `data:` payload, and the stream ends on a terminal event, one of `response.completed`, `response.failed` or `response.incomplete`; there is no `[DONE]` sentinel. OpenAI-compatible, so existing Responses API code runs unmodified.

## Headers

- `Authorization` string, required

## Request body

- ResponseRequest — OpenAI-compatible Responses API request.
  - `model` string, required — The ASI:One model to use.
  - `input` union, required — Text, or a list of input items, to generate a response for. Input item content parts are text; an image part is rejected with a 400. Send images to /v1/chat/completions as an image_url content part.
    - string
    - ResponseRequestInputOneOf1Items[]
  - `instructions` string — System/developer instructions inserted ahead of the input.
  - `stream` boolean — If true, response events are streamed as server-sent events.
  - `background` boolean — If true, run the response as a background task; poll it with the retrieve endpoint or stop it with cancel.
  - `store` boolean — Whether to persist the response so it can be retrieved by id.
  - `previous_response_id` string — The id of a previous response to continue from.
  - `max_output_tokens` integer — Upper bound on tokens generated for the response.
  - `temperature` number, double — Sampling temperature.
  - `top_p` number, double — Nucleus sampling probability mass.
  - `tools` ResponseRequestToolsItems[] — A list of tools the model may call, in either the flat Responses shape or the nested Chat Completions shape. See the Tool Calling guide.
    - union
      - ResponsesFunctionTool — The flat function-tool shape accepted on `/v1/responses`, where the function's fields sit at the top level. The nested `FunctionTool` shape is accepted here too.
        - `type` 'function', required — Always `function`. Any other tool type is rejected with a 400.
        - `name` string, required — Name of the function. The model uses this to refer to the call.
        - `description` string — What the function does and when to use it. The model selects tools from this text, so it is worth writing carefully.
        - `parameters` object, required — JSON Schema describing the function's arguments.
        - `strict` boolean — Whether the model must follow the parameter schema exactly. Requires `additionalProperties: false` and every property listed in `required`.
      - FunctionTool — A function the model may call. Your code defines the schema and executes the call. Only function tools are supported.
        - `type` 'function', required — Always `function`. Any other tool type is rejected with a 400.
        - `function` FunctionToolFunction, required
          - `name` string, required — Name of the function. The model uses this to refer to the call.
          - `description` string — What the function does and when to use it. The model selects tools from this text, so it is worth writing carefully.
          - `parameters` object — JSON Schema describing the function's arguments.
          - `strict` boolean — Whether the model must follow the parameter schema exactly. Requires `additionalProperties: false` and every property listed in `required`.
  - `tool_choice` union — Controls which (if any) tool is called.
    - 'auto' | 'none' | 'required'
    - object
  - `parallel_tool_calls` boolean — Whether the model may call several tools in one turn.
  - `text` ResponseRequestText — Output format configuration. `text.format` takes precedence over `response_format`.
    - `format` union — The flat output-format shape used by `/v1/responses`. An unrecognised `type` is rejected with a 400.
      - TextFormat0
        - `type` 'text' | 'json_object', required
      - TextFormat1
        - `type` 'json_schema', required
        - `name` string, required — Name of the schema. Required when `type` is `json_schema`.
        - `description` string — What the schema is for.
        - `schema` object — The JSON Schema the reply must conform to.
        - `strict` boolean — Whether the reply must match the schema exactly.
  - `reasoning` ResponseRequestReasoning — Reasoning configuration. See the Reasoning guide.
    - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' — How much the model may reason before answering. `none` disables reasoning. Any other value is rejected with a 400.
  - `enable_thinking` boolean — ASI:One extension. Whether the model reasons before answering. Used when `reasoning.effort` is absent.
  - `thinking_budget` integer — ASI:One extension. Maximum tokens the model may spend reasoning.
  - `metadata` object — Up to 16 key-value string pairs attached to the response.

## Response `200`

A response object, or an SSE stream of response events when `stream` is true.

- ResponseObject — An OpenAI-compatible response object. See the linked OpenAI reference for the full schema.
  - `id` string
  - `object` string
  - `status` 'queued' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'incomplete' — Lifecycle status. `queued` and `in_progress` mean the run is still going; `completed`, `failed`, `cancelled` and `incomplete` are terminal.
  - `model` string
  - `output` ResponseObjectOutputItems[]
  - `usage` ResponseObjectUsage — Token usage for the response.
    - `input_tokens` integer
    - `input_tokens_details` ResponseObjectUsageInputTokensDetails — Breakdown of the input tokens.
      - `cached_tokens` integer — Input tokens served from cache. These still count toward `input_tokens`.
    - `output_tokens` integer
    - `output_tokens_details` ResponseObjectUsageOutputTokensDetails — Breakdown of the output tokens.
      - `reasoning_tokens` integer — Tokens spent reasoning before answering. `0` when reasoning was not requested.
    - `total_tokens` integer

## Other responses

- `400` — The request was malformed, or a parameter was missing or invalid.
- `401` — The API key is missing or invalid.
- `402` — The organization's account is blocked.
- `403` — The API key is not permitted to perform this operation.
- `404` — The requested model or resource does not exist.
- `409` — The `previous_response_id` refers to a response that has not finished. Wait for it to reach a terminal status, then retry.
- `429` — The rate limit for your plan has been exceeded.
- `500` — An unexpected error occurred while handling the request.
- `502` — An upstream service failed while handling the request.

---

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