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

# Create a model response

`POST /v1/responses`

Creates a model response from text, image, or file input. Supports structured output, tool calls, conversation state, background processing, and streaming.

## Request body

- ResponsesRequest — Request body for the OpenAI-compatible Responses API.
  - `model` string — Model ID used to generate the response. See [Supported Models](/grids/en/start/pricing/llm).
  - `input` union — Text, image, or file input to the model. A string is treated as a user message.
    - string
    - ResponseInputItem[]
      - `type` string
      - `role` 'user' | 'assistant' | 'system' | 'developer'
      - `content` union
        - string
        - ResponseInputContent[]
          - `type` 'input_text' | 'input_image' | 'input_file', required
          - `text` string
          - `image_url` string
          - `file_id` string
          - `file_url` string
          - `file_data` string
          - `filename` string
          - `detail` 'low' | 'high' | 'auto'
      - `id` string
      - `call_id` string
      - `output` unknown
  - `instructions` string — A system or developer message inserted into the model context. It is not carried over when previous_response_id is used.
  - `previous_response_id` string — ID of the previous response for multi-turn interactions. Cannot be used together with conversation.
  - `conversation` union — Conversation that this response belongs to.
    - string
    - object
      - `id` string, required
  - `background` boolean — Whether to run the response in the background.
  - `include` string[] — Additional output data to include in the response.
  - `max_output_tokens` integer — Maximum number of generated tokens, including visible output and reasoning tokens.
  - `max_tool_calls` integer — Maximum total number of built-in tool calls processed for this response.
  - `metadata` object — Up to 16 string key-value pairs attached to the response.
  - `parallel_tool_calls` boolean — Whether the model may call tools in parallel.
  - `prompt` object — Reference to a reusable prompt template.
    - `id` string, required
    - `version` string
    - `variables` object
  - `prompt_cache_key` string — Stable key used to improve prompt cache hit rates.
  - `prompt_cache_retention` 'in-memory' | '24h' — Prompt cache retention policy.
  - `reasoning` object — Reasoning configuration for supported models.
    - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
    - `summary` 'auto' | 'concise' | 'detailed'
  - `safety_identifier` string — Stable identifier for the end user, used for abuse detection.
  - `service_tier` 'auto' | 'default' | 'flex' | 'scale' | 'priority'
  - `store` boolean — Whether to store the generated response for later retrieval.
  - `stream` boolean — Whether to stream response events using server-sent events.
  - `stream_options` object — Streaming options. Set only when stream is true.
    - `include_obfuscation` boolean
  - `temperature` number — Sampling temperature. Change this or top_p, but generally not both.
  - `text` ResponseTextConfig
    - `format` object — Text, JSON object, or JSON schema output format.
    - `verbosity` 'low' | 'medium' | 'high'
  - `tool_choice` union — Controls which tool or tools the model may call.
    - 'none' | 'auto' | 'required'
    - object
  - `tools` object[] — Tools available to the model, including function and supported built-in tools.
  - `top_logprobs` integer
  - `top_p` number
  - `truncation` 'auto' | 'disabled'

## Response `200`

Successful response. When stream is true, the endpoint returns server-sent events.

- ResponseObject
  - `id` string, required
  - `object` 'response', required
  - `created_at` number, required
  - `status` 'completed' | 'failed' | 'in_progress' | 'cancelled' | 'queued' | 'incomplete', required
  - `error` object, nullable
    - `code` string
    - `message` string
  - `incomplete_details` object, nullable
    - `reason` 'max_output_tokens' | 'content_filter'
  - `model` string, required
  - `output` ResponseOutputItem[], required
    - `type` string
    - `id` string
    - `status` string
    - `role` 'assistant'
    - `content` ResponseOutputContent[]
      - `type` 'output_text' | 'refusal', required
      - `text` string
      - `refusal` string
      - `annotations` object[]
      - `logprobs` object[]
    - `call_id` string
    - `name` string
    - `arguments` string
  - `output_text` string — SDK convenience property containing aggregated text output.
  - `previous_response_id` string, nullable
  - `store` boolean
  - `usage` ResponseUsage
    - `input_tokens` integer
    - `input_tokens_details` object
      - `cached_tokens` integer
    - `output_tokens` integer
    - `output_tokens_details` object
      - `reasoning_tokens` integer
    - `total_tokens` integer
  - `metadata` object

## Other responses

- `400` — Parameter error
- `401` — Authorization failed

---

[API](https://skmtc.net/ttapi/apis/flowmusic-api-docs.md) · [All operations](https://skmtc.net/ttapi/apis/flowmusic-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ttapi/flowmusic-api-docs/versions/f27f8a59dbd0/schema)