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

# Create a response

Creates a streaming or non-streaming response using the OpenAI Responses API format. Supports text, images, files, audio, video, function calling, web search, file search, code interpreter, reasoning, and more.

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token. Use your API key as the bearer token in the Authorization header.

  Format: `Bearer <SUNRA_KEY>`
</ParamField>

## Request

This endpoint expects an object.

<ParamField body="model" type="string" required>
  Model ID used to generate the response. Browse available models at [sunra.ai/models](https://sunra.ai/models).
</ParamField>

<ParamField body="provider" type="object">
  Optional provider routing preferences. Omit for automatic routing. See [Provider routing](/llm/provider-routing) for supported fields and provider discovery.
</ParamField>

<ParamField body="input" type="string | object[]">
  Input for the response request. Can be a string or an array of input items including messages, function calls, function call outputs, reasoning items, and output messages.

  <Expandable title="input item types">
    <Tabs>
      <Tab title="EasyInputMessage">
        <ParamField body="role" type="string" required>
          The role of the message author. Supported values: `user`, `assistant`, `system`, `developer`.
        </ParamField>

        <ParamField body="content" type="string | object[]">
          The content of the message. Can be a string or an array of content parts.

          <Expandable title="content part types">
            <Tabs>
              <Tab title="InputText">
                <ParamField body="type" type="string" required>
                  Value: `input_text`.
                </ParamField>

                <ParamField body="text" type="string" required>
                  The text content.
                </ParamField>
              </Tab>

              <Tab title="InputImage">
                <ParamField body="type" type="string" required>
                  Value: `input_image`.
                </ParamField>

                <ParamField body="image_url" type="string | null">
                  The URL of the image, or a base64-encoded data URI.
                </ParamField>

                <ParamField body="detail" type="string" required>
                  Image detail level. Supported values: `auto`, `high`, `low`.
                </ParamField>
              </Tab>

              <Tab title="InputFile">
                <ParamField body="type" type="string" required>
                  Value: `input_file`.
                </ParamField>

                <ParamField body="file_id" type="string | null">
                  The ID of a previously uploaded file.
                </ParamField>

                <ParamField body="file_data" type="string">
                  Base64-encoded file data.
                </ParamField>

                <ParamField body="filename" type="string">
                  The name of the file.
                </ParamField>

                <ParamField body="file_url" type="string">
                  The URL of the file.
                </ParamField>
              </Tab>

              <Tab title="InputAudio">
                <ParamField body="type" type="string" required>
                  Value: `input_audio`.
                </ParamField>

                <ParamField body="input_audio" type="object" required>
                  Audio input data.

                  <Expandable title="properties">
                    <ParamField body="data" type="string" required>
                      Base64-encoded audio data.
                    </ParamField>

                    <ParamField body="format" type="string" required>
                      Audio format. Supported values: `mp3`, `wav`.
                    </ParamField>
                  </Expandable>
                </ParamField>
              </Tab>

              <Tab title="InputVideo">
                <ParamField body="type" type="string" required>
                  Value: `input_video`.
                </ParamField>

                <ParamField body="video_url" type="string" required>
                  A base64 data URL or remote URL that resolves to a video file.
                </ParamField>
              </Tab>
            </Tabs>
          </Expandable>
        </ParamField>

        <ParamField body="type" type="string">
          Value: `message`. Optional for easy input messages.
        </ParamField>

        <ParamField body="phase" type="string">
          The phase of an assistant message. Supported values: `commentary`, `final_answer`. For follow-up requests, preserve and resend phase on all assistant messages.
        </ParamField>
      </Tab>

      <Tab title="InputMessageItem">
        <ParamField body="id" type="string" required>
          The ID of the message item.
        </ParamField>

        <ParamField body="type" type="string">
          Value: `message`.
        </ParamField>

        <ParamField body="role" type="string" required>
          The role. Supported values: `user`, `system`, `developer`.
        </ParamField>

        <ParamField body="content" type="object[] | null">
          Array of content parts (`input_text`, `input_image`, `input_file`, `input_audio`, `input_video`).
        </ParamField>
      </Tab>

      <Tab title="OutputMessage">
        <ParamField body="id" type="string" required>
          The ID of the output message.
        </ParamField>

        <ParamField body="type" type="string" required>
          Value: `message`.
        </ParamField>

        <ParamField body="role" type="string" required>
          Value: `assistant`.
        </ParamField>

        <ParamField body="status" type="string">
          Status of the message. Supported values: `completed`, `incomplete`, `in_progress`.
        </ParamField>

        <ParamField body="content" type="string | object[]" required>
          Array of content items (`output_text`, `refusal`).
        </ParamField>

        <ParamField body="phase" type="string">
          The phase. Supported values: `commentary`, `final_answer`.
        </ParamField>
      </Tab>

      <Tab title="FunctionCall">
        <ParamField body="type" type="string" required>
          Value: `function_call`.
        </ParamField>

        <ParamField body="id" type="string" required>
          The unique ID of the function call item.
        </ParamField>

        <ParamField body="call_id" type="string" required>
          The call ID to match with the function call output.
        </ParamField>

        <ParamField body="name" type="string" required>
          The name of the function.
        </ParamField>

        <ParamField body="arguments" type="string" required>
          The arguments in JSON string format.
        </ParamField>

        <ParamField body="status" type="string">
          Status. Supported values: `in_progress`, `completed`, `incomplete`.
        </ParamField>
      </Tab>

      <Tab title="FunctionCallOutput">
        <ParamField body="type" type="string" required>
          Value: `function_call_output`.
        </ParamField>

        <ParamField body="call_id" type="string" required>
          The call ID of the function call being responded to.
        </ParamField>

        <ParamField body="output" type="string | object[]" required>
          The output of the function call. Can be a string or array of content parts (`input_text`, `input_image`, `input_file`).
        </ParamField>

        <ParamField body="id" type="string | null">
          Optional ID for the output item.
        </ParamField>

        <ParamField body="status" type="string">
          Status. Supported values: `in_progress`, `completed`, `incomplete`.
        </ParamField>
      </Tab>

      <Tab title="Reasoning">
        <ParamField body="type" type="string" required>
          Value: `reasoning`.
        </ParamField>

        <ParamField body="id" type="string" required>
          The unique ID of the reasoning item.
        </ParamField>

        <ParamField body="summary" type="object[]">
          Array of reasoning summary text items, each with `type: "summary_text"` and `text`.
        </ParamField>

        <ParamField body="content" type="object[] | null">
          Array of reasoning text content items, each with `type: "reasoning_text"` and `text`.
        </ParamField>

        <ParamField body="encrypted_content" type="string | null">
          Encrypted reasoning content for models that support it.
        </ParamField>

        <ParamField body="status" type="string">
          Status. Supported values: `completed`, `incomplete`, `in_progress`.
        </ParamField>

        <ParamField body="signature" type="string | null">
          A signature for the reasoning content, used for verification.
        </ParamField>
      </Tab>
    </Tabs>
  </Expandable>
</ParamField>

<ParamField body="instructions" type="string | null">
  Inserts a system (or developer) message as the first item in the model's context. When used with `input`, the instructions are inserted at the start of the input.
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  If set to `true`, the response will be streamed using server-sent events (SSE). Streams are subject to an idle timeout and a lifetime ceiling — see [Output limits and stream lifetime](/llm/limits#stream-lifetime).
</ParamField>

<ParamField body="max_output_tokens" type="number | null">
  An upper bound for the number of output tokens, including visible output tokens and reasoning tokens. A value above the model's own ceiling is rejected with `400` rather than reduced. See [Output limits](/llm/limits).
</ParamField>

<ParamField body="temperature" type="number | null">
  Sampling temperature between 0 and 2. Higher values increase randomness.
</ParamField>

<ParamField body="top_p" type="number | null">
  Nucleus sampling parameter. An alternative to sampling with temperature.
</ParamField>

<ParamField body="top_k" type="number">
  Sample only from the top K options for each subsequent token. Used to remove "long tail" low-probability responses.
</ParamField>

<ParamField body="frequency_penalty" type="number | null">
  Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text.
</ParamField>

<ParamField body="presence_penalty" type="number | null">
  Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they already appear in the text.
</ParamField>

<ParamField body="top_logprobs" type="integer | null">
  An integer specifying the number of most likely tokens to return at each token position.
</ParamField>

<ParamField body="max_tool_calls" type="integer | null">
  Maximum number of tool calls the model can make in a single response.
</ParamField>

<ParamField body="tools" type="object[]">
  An array of tools the model may call.

  <Expandable title="tool types">
    <Tabs>
      <Tab title="Function">
        <ParamField body="type" type="string" required>
          Value: `function`.
        </ParamField>

        <ParamField body="name" type="string" required>
          The name of the function.
        </ParamField>

        <ParamField body="description" type="string | null">
          A description of the function.
        </ParamField>

        <ParamField body="parameters" type="object | null">
          A JSON Schema object defining the function parameters.
        </ParamField>

        <ParamField body="strict" type="boolean | null">
          Whether strict schema adherence is enabled.
        </ParamField>
      </Tab>

      <Tab title="Web Search Preview">
        <ParamField body="type" type="string" required>
          Value: `web_search_preview` or `web_search_preview_2025_03_11`.
        </ParamField>

        <ParamField body="search_context_size" type="string">
          Size of the search context. Supported values: `low`, `medium`, `high`.
        </ParamField>

        <ParamField body="user_location" type="object">
          User location information for search personalization.

          <Expandable title="properties">
            <ParamField body="type" type="string" required>
              Value: `approximate`.
            </ParamField>

            <ParamField body="city" type="string | null">
              City name.
            </ParamField>

            <ParamField body="country" type="string | null">
              Country name.
            </ParamField>

            <ParamField body="region" type="string | null">
              Region/state name.
            </ParamField>

            <ParamField body="timezone" type="string | null">
              IANA timezone name.
            </ParamField>
          </Expandable>
        </ParamField>
      </Tab>

      <Tab title="Web Search">
        <ParamField body="type" type="string" required>
          Value: `web_search` or `web_search_2025_08_26`.
        </ParamField>

        <ParamField body="search_context_size" type="string">
          Size of the search context. Supported values: `low`, `medium`, `high`.
        </ParamField>

        <ParamField body="filters" type="object | null">
          Domain filters for search results.

          <Expandable title="properties">
            <ParamField body="allowed_domains" type="string[] | null">
              List of allowed domains to restrict search results to.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="user_location" type="object">
          User location information for search personalization.
        </ParamField>
      </Tab>

      <Tab title="File Search">
        <ParamField body="type" type="string" required>
          Value: `file_search`.
        </ParamField>

        <ParamField body="vector_store_ids" type="string[]" required>
          IDs of vector stores to search.
        </ParamField>

        <ParamField body="filters" type="object">
          Filters for file search. Can be a comparison filter (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`) or a compound filter (`and`, `or`).
        </ParamField>

        <ParamField body="max_num_results" type="integer">
          Maximum number of results to return.
        </ParamField>

        <ParamField body="ranking_options" type="object">
          Ranking options for search results.

          <Expandable title="properties">
            <ParamField body="ranker" type="string">
              Ranker to use. Supported values: `auto`, `default-2024-11-15`.
            </ParamField>

            <ParamField body="score_threshold" type="number">
              Minimum score threshold for results.
            </ParamField>
          </Expandable>
        </ParamField>
      </Tab>

      <Tab title="Computer Use Preview">
        <ParamField body="type" type="string" required>
          Value: `computer_use_preview`.
        </ParamField>

        <ParamField body="display_height" type="number" required>
          Display height in pixels.
        </ParamField>

        <ParamField body="display_width" type="number" required>
          Display width in pixels.
        </ParamField>

        <ParamField body="environment" type="string" required>
          The environment. Supported values: `windows`, `mac`, `linux`, `ubuntu`, `browser`.
        </ParamField>
      </Tab>

      <Tab title="Code Interpreter">
        <ParamField body="type" type="string" required>
          Value: `code_interpreter`.
        </ParamField>

        <ParamField body="container" type="string | object" required>
          Container configuration. Can be a container ID string or an object.

          <Expandable title="properties (when object)">
            <ParamField body="type" type="string" required>
              Value: `auto`.
            </ParamField>

            <ParamField body="file_ids" type="string[]">
              File IDs to make available in the container.
            </ParamField>

            <ParamField body="memory_limit" type="string | null">
              Memory limit. Supported values: `1g`, `4g`, `16g`, `64g`.
            </ParamField>
          </Expandable>
        </ParamField>
      </Tab>

      <Tab title="MCP">
        <ParamField body="type" type="string" required>
          Value: `mcp`.
        </ParamField>

        <ParamField body="server_label" type="string" required>
          A label for the MCP server.
        </ParamField>

        <ParamField body="server_url" type="string">
          The URL of the MCP server.
        </ParamField>

        <ParamField body="allowed_tools" type="string[] | object">
          Tools the model is allowed to use from this server.
        </ParamField>

        <ParamField body="require_approval" type="string | object">
          Approval requirements for tool calls. String values: `always`, `never`. Can also be an object with `never` and `always` lists.
        </ParamField>

        <ParamField body="headers" type="object | null">
          Custom headers to include in requests to the MCP server.
        </ParamField>

        <ParamField body="server_description" type="string">
          Description of the MCP server.
        </ParamField>
      </Tab>

      <Tab title="Image Generation">
        <ParamField body="type" type="string" required>
          Value: `image_generation`.
        </ParamField>

        <ParamField body="background" type="string">
          Background type. Supported values: `transparent`, `opaque`, `auto`.
        </ParamField>

        <ParamField body="model" type="string">
          Model to use. Supported values: `gpt-image-1`, `gpt-image-1-mini`.
        </ParamField>

        <ParamField body="quality" type="string">
          Image quality. Supported values: `low`, `medium`, `high`, `auto`.
        </ParamField>

        <ParamField body="size" type="string">
          Image size. Supported values: `1024x1024`, `1024x1536`, `1536x1024`, `auto`.
        </ParamField>

        <ParamField body="output_format" type="string">
          Output format. Supported values: `png`, `webp`, `jpeg`.
        </ParamField>

        <ParamField body="moderation" type="string">
          Moderation level. Supported values: `auto`, `low`.
        </ParamField>

        <ParamField body="output_compression" type="number">
          Compression level for output.
        </ParamField>

        <ParamField body="partial_images" type="number">
          Number of partial images to return during generation.
        </ParamField>
      </Tab>
    </Tabs>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Controls tool selection behavior. String values: `none`, `auto`, `required`. Can also specify a particular function or tool type.

  <Expandable title="object variants">
    <Tabs>
      <Tab title="function">
        <ParamField body="type" type="string" required>
          Value: `function`.
        </ParamField>

        <ParamField body="name" type="string" required>
          The name of the function to use.
        </ParamField>
      </Tab>

      <Tab title="web_search_preview">
        <ParamField body="type" type="string" required>
          Value: `web_search_preview` or `web_search_preview_2025_03_11`.
        </ParamField>
      </Tab>
    </Tabs>
  </Expandable>
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean | null">
  Whether to allow the model to run tool calls in parallel.
</ParamField>

<ParamField body="text" type="object">
  Configuration for text response format.

  <Expandable title="properties">
    <ParamField body="format" type="object">
      The text format configuration.

      <Expandable title="format types">
        <Tabs>
          <Tab title="text">
            <ParamField body="type" type="string" required>
              Value: `text`.
            </ParamField>
          </Tab>

          <Tab title="json_object">
            <ParamField body="type" type="string" required>
              Value: `json_object`.
            </ParamField>
          </Tab>

          <Tab title="json_schema">
            <ParamField body="type" type="string" required>
              Value: `json_schema`.
            </ParamField>

            <ParamField body="name" type="string" required>
              The name of the response format.
            </ParamField>

            <ParamField body="schema" type="object" required>
              The JSON schema definition.
            </ParamField>

            <ParamField body="description" type="string">
              Description of the schema.
            </ParamField>

            <ParamField body="strict" type="boolean | null">
              Whether strict schema adherence is enabled.
            </ParamField>
          </Tab>
        </Tabs>
      </Expandable>
    </ParamField>

    <ParamField body="verbosity" type="string | null">
      Controls the verbosity of the text output. Supported values: `high`, `medium`, `low`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="reasoning" type="object">
  Configuration for reasoning output.

  <Expandable title="properties">
    <ParamField body="effort" type="string">
      Constrains effort on reasoning. Supported values: `xhigh`, `high`, `medium`, `low`, `minimal`, `none`.
    </ParamField>

    <ParamField body="summary" type="string">
      Controls reasoning summary verbosity. Supported values: `auto`, `concise`, `detailed`.
    </ParamField>

    <ParamField body="max_tokens" type="number | null">
      Maximum number of tokens for reasoning.
    </ParamField>

    <ParamField body="enabled" type="boolean | null">
      Whether reasoning is enabled.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="modalities" type="string[]">
  Output modalities for the response. Supported values: `text`, `image`.
</ParamField>

<ParamField body="previous_response_id" type="string | null">
  The ID of a previous response to use as context for this request.
</ParamField>

<ParamField body="include" type="string[]">
  Additional fields to include in the response. Supported values: `file_search_call.results`, `message.input_image.image_url`, `computer_call_output.output.image_url`, `reasoning.encrypted_content`, `code_interpreter_call.outputs`.
</ParamField>

<ParamField body="store" type="boolean">
  Whether to store the generated response for later retrieval.
</ParamField>

<ParamField body="service_tier" type="string">
  The service tier to use for this request. Supported values: `auto`.
</ParamField>

<ParamField body="truncation" type="string">
  Truncation strategy. Supported values: `auto`, `disabled`.
</ParamField>

<ParamField body="background" type="boolean | null">
  Whether to run the request in the background.
</ParamField>

<ParamField body="metadata" type="object">
  Set of key-value pairs that can be attached to the response. Keys must be ≤64 characters. Values must be ≤512 characters. Maximum 16 pairs allowed.
</ParamField>

<ParamField body="user" type="string">
  A unique identifier representing your end-user. Maximum of 128 characters.
</ParamField>

## Response

Successful response object.

<ResponseField name="id" type="string">
  Unique response identifier.
</ResponseField>

<ResponseField name="object" type="string">
  The object type. Always `response`.
</ResponseField>

<ResponseField name="created_at" type="number">
  Unix timestamp (in seconds) of when the response was created.
</ResponseField>

<ResponseField name="completed_at" type="number | null">
  Unix timestamp (in seconds) of when the response completed.
</ResponseField>

<ResponseField name="status" type="string">
  The status of the response. Possible values: `completed`, `incomplete`, `in_progress`, `failed`, `cancelled`, `queued`.
</ResponseField>

<ResponseField name="model" type="string">
  The model used for generating the response.
</ResponseField>

<ResponseField name="output" type="object[]">
  An array of output items generated by the model.

  <Expandable title="output item types">
    <Tabs>
      <Tab title="OutputMessage">
        <ResponseField name="type" type="string">
          Value: `message`.
        </ResponseField>

        <ResponseField name="id" type="string">
          The unique ID of the output message.
        </ResponseField>

        <ResponseField name="role" type="string">
          Always `assistant`.
        </ResponseField>

        <ResponseField name="status" type="string">
          Status of the message. Possible values: `completed`, `incomplete`, `in_progress`.
        </ResponseField>

        <ResponseField name="content" type="object[]">
          The content of the output message.

          <Expandable title="content types">
            <Tabs>
              <Tab title="OutputText">
                <ResponseField name="type" type="string">
                  Value: `output_text`.
                </ResponseField>

                <ResponseField name="text" type="string">
                  The generated text content.
                </ResponseField>

                <ResponseField name="annotations" type="object[]">
                  Annotations for the content. Types include:

                  * `file_citation`: `{type, file_id, filename, index}`
                  * `url_citation`: `{type, url, title, start_index, end_index}`
                  * `file_path`: `{type, file_id, index}`
                </ResponseField>

                <ResponseField name="logprobs" type="object[]">
                  Log probability information for output tokens. Each item contains `token`, `bytes`, `logprob`, and `top_logprobs`.
                </ResponseField>
              </Tab>

              <Tab title="Refusal">
                <ResponseField name="type" type="string">
                  Value: `refusal`.
                </ResponseField>

                <ResponseField name="refusal" type="string">
                  The refusal message.
                </ResponseField>
              </Tab>
            </Tabs>
          </Expandable>
        </ResponseField>

        <ResponseField name="phase" type="string">
          The phase of the message. Possible values: `commentary`, `final_answer`.
        </ResponseField>
      </Tab>

      <Tab title="Reasoning">
        <ResponseField name="type" type="string">
          Value: `reasoning`.
        </ResponseField>

        <ResponseField name="id" type="string">
          The unique ID of the reasoning item.
        </ResponseField>

        <ResponseField name="content" type="object[] | null">
          Array of reasoning text items, each with `type: "reasoning_text"` and `text`.
        </ResponseField>

        <ResponseField name="summary" type="object[]">
          Array of reasoning summary items, each with `type: "summary_text"` and `text`.
        </ResponseField>

        <ResponseField name="encrypted_content" type="string | null">
          Encrypted reasoning content.
        </ResponseField>

        <ResponseField name="status" type="string">
          Status. Possible values: `completed`, `incomplete`, `in_progress`.
        </ResponseField>

        <ResponseField name="signature" type="string | null">
          A signature for the reasoning content, used for verification.
        </ResponseField>

        <ResponseField name="format" type="string | null">
          The format of the reasoning content. Possible values: `unknown`, `openai-responses-v1`, `azure-openai-responses-v1`, `xai-responses-v1`, `anthropic-claude-v1`, `google-gemini-v1`.
        </ResponseField>
      </Tab>

      <Tab title="FunctionCall">
        <ResponseField name="type" type="string">
          Value: `function_call`.
        </ResponseField>

        <ResponseField name="id" type="string">
          The unique ID of the function call.
        </ResponseField>

        <ResponseField name="name" type="string">
          The name of the function called.
        </ResponseField>

        <ResponseField name="arguments" type="string">
          The arguments in JSON string format.
        </ResponseField>

        <ResponseField name="call_id" type="string">
          The call ID for matching with function call output.
        </ResponseField>

        <ResponseField name="status" type="string">
          Status. Possible values: `completed`, `incomplete`, `in_progress`.
        </ResponseField>
      </Tab>

      <Tab title="WebSearchCall">
        <ResponseField name="type" type="string">
          Value: `web_search_call`.
        </ResponseField>

        <ResponseField name="id" type="string">
          The unique ID of the web search call.
        </ResponseField>

        <ResponseField name="action" type="object">
          The search action. Types include:

          * `search`: `{type, query, queries?, sources?}`
          * `open_page`: `{type, url}`
          * `find_in_page`: `{type, pattern, url}`
        </ResponseField>

        <ResponseField name="status" type="string">
          Status. Possible values: `completed`, `searching`, `in_progress`, `failed`.
        </ResponseField>
      </Tab>

      <Tab title="FileSearchCall">
        <ResponseField name="type" type="string">
          Value: `file_search_call`.
        </ResponseField>

        <ResponseField name="id" type="string">
          The unique ID of the file search call.
        </ResponseField>

        <ResponseField name="queries" type="string[]">
          The search queries used.
        </ResponseField>

        <ResponseField name="status" type="string">
          Status. Possible values: `completed`, `searching`, `in_progress`, `failed`.
        </ResponseField>
      </Tab>

      <Tab title="ImageGenerationCall">
        <ResponseField name="type" type="string">
          Value: `image_generation_call`.
        </ResponseField>

        <ResponseField name="id" type="string">
          The unique ID of the image generation call.
        </ResponseField>

        <ResponseField name="result" type="string | null">
          The generated image data (base64).
        </ResponseField>

        <ResponseField name="status" type="string">
          Status. Possible values: `in_progress`, `completed`, `generating`, `failed`.
        </ResponseField>
      </Tab>
    </Tabs>
  </Expandable>
</ResponseField>

<ResponseField name="output_text" type="string">
  Convenience field containing the concatenated text output from all output messages.
</ResponseField>

<ResponseField name="incomplete_details" type="object | null">
  Details about why the response is incomplete, if applicable.

  <Expandable title="properties">
    <ResponseField name="reason" type="string">
      The reason. Possible values: `max_output_tokens`, `content_filter`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object | null">
  An error object if the generation failed.

  <Expandable title="properties">
    <ResponseField name="code" type="string">
      Error code. Possible values: `server_error`, `rate_limit_exceeded`, `invalid_prompt`, `vector_store_timeout`, `invalid_image`, `invalid_image_format`, `invalid_base64_image`, `invalid_image_url`, `image_too_large`, `image_too_small`, `image_parse_error`, `image_content_policy_violation`, `invalid_image_mode`, `image_file_too_large`, `unsupported_image_media_type`, `empty_image_file`, `failed_to_download_image`, `image_file_not_found`.
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics for the response.

  <Expandable title="properties">
    <ResponseField name="input_tokens" type="number">
      The number of input tokens.
    </ResponseField>

    <ResponseField name="output_tokens" type="number">
      The number of output tokens.
    </ResponseField>

    <ResponseField name="total_tokens" type="number">
      The total number of tokens.
    </ResponseField>

    <ResponseField name="input_tokens_details" type="object">
      Breakdown of input tokens.

      <Expandable title="properties">
        <ResponseField name="cached_tokens" type="number">
          The number of cached tokens.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="output_tokens_details" type="object">
      Breakdown of output tokens.

      <Expandable title="properties">
        <ResponseField name="reasoning_tokens" type="number">
          The number of reasoning tokens.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="temperature" type="number | null">
  The sampling temperature used.
</ResponseField>

<ResponseField name="top_p" type="number | null">
  The nucleus sampling value used.
</ResponseField>

<ResponseField name="max_output_tokens" type="number | null">
  The max output tokens setting used.
</ResponseField>

<ResponseField name="top_logprobs" type="number">
  The top logprobs setting used.
</ResponseField>

<ResponseField name="max_tool_calls" type="number | null">
  The max tool calls setting used.
</ResponseField>

<ResponseField name="presence_penalty" type="number | null">
  The presence penalty used.
</ResponseField>

<ResponseField name="frequency_penalty" type="number | null">
  The frequency penalty used.
</ResponseField>

<ResponseField name="instructions" type="string | object[] | null">
  The instructions/system message used.
</ResponseField>

<ResponseField name="metadata" type="object">
  The metadata attached to the response.
</ResponseField>

<ResponseField name="tools" type="object[]">
  The tools configuration used.
</ResponseField>

<ResponseField name="tool_choice" type="string | object">
  The tool choice configuration used.
</ResponseField>

<ResponseField name="parallel_tool_calls" type="boolean">
  Whether parallel tool calls was enabled.
</ResponseField>

<ResponseField name="reasoning" type="object">
  The reasoning configuration used.
</ResponseField>

<ResponseField name="service_tier" type="string">
  The service tier used. Possible values: `auto`, `default`, `flex`, `priority`, `scale`.
</ResponseField>

<ResponseField name="store" type="boolean">
  Whether the response was stored.
</ResponseField>

<ResponseField name="truncation" type="string">
  The truncation strategy used. Possible values: `auto`, `disabled`.
</ResponseField>

<ResponseField name="text" type="object">
  The text format configuration used.
</ResponseField>

<ResponseField name="previous_response_id" type="string | null">
  The ID of the previous response used as context.
</ResponseField>

<ResponseField name="background" type="boolean | null">
  Whether the request ran in the background.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api-llm.sunra.ai/v1/responses \
    -H "Authorization: Bearer <SUNRA_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "google/gemini-2.5-flash",
      "input": [
        {
          "type": "message",
          "role": "user",
          "content": "Hello, how are you?"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api-llm.sunra.ai/v1/responses",
      headers={
          "Authorization": "Bearer <SUNRA_KEY>",
          "Content-Type": "application/json"
      },
      json={
          "model": "google/gemini-2.5-flash",
          "input": [
              {
                  "type": "message",
                  "role": "user",
                  "content": "Hello, how are you?"
              }
          ]
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api-llm.sunra.ai/v1/responses", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <SUNRA_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "google/gemini-2.5-flash",
      input: [
        {
          type: "message",
          role: "user",
          content: "Hello, how are you?"
        }
      ]
    })
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "resp-abc123",
    "object": "response",
    "created_at": 1704067200,
    "completed_at": 1704067201,
    "status": "completed",
    "model": "google/gemini-2.5-flash",
    "output": [
      {
        "type": "message",
        "id": "msg_abc123",
        "role": "assistant",
        "status": "completed",
        "content": [
          {
            "type": "output_text",
            "text": "Hello! I'm doing well, thank you for asking. How can I help you today?",
            "annotations": []
          }
        ]
      }
    ],
    "output_text": "Hello! I'm doing well, thank you for asking. How can I help you today?",
    "incomplete_details": null,
    "error": null,
    "temperature": 1.0,
    "top_p": 1.0,
    "max_output_tokens": null,
    "top_logprobs": 0,
    "presence_penalty": null,
    "frequency_penalty": null,
    "instructions": null,
    "metadata": {},
    "tools": [],
    "tool_choice": "auto",
    "parallel_tool_calls": true,
    "reasoning": null,
    "service_tier": "auto",
    "store": true,
    "truncation": "disabled",
    "text": {
      "format": {
        "type": "text"
      }
    },
    "usage": {
      "input_tokens": 15,
      "output_tokens": 18,
      "total_tokens": 33,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens_details": {
        "reasoning_tokens": 0
      }
    }
  }
  ```
</ResponseExample>