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

# Create Response

> Creates a response using the OpenAI Responses API format

The Responses API is OpenAI's stateful response protocol. AI Sonar exposes it only when the model details advertise the Responses request format and a same-protocol route is currently available; this is not inferred from a `gpt-*` name or provider. Native Responses requests stay on Responses endpoints and never fall back through Chat Completions.

AI Sonar preserves the request JSON shape, including unknown fields, explicit `null`, and empty arrays, and forwards it best-effort. Unknown or future fields remain subject to the selected service's support.

## Request Body

<ParamField body="model" type="string" required>
  ID of the model to use. See [Models](https://aisonar.dev/models) for available options.
</ParamField>

<ParamField body="input" type="string | array">
  Input for the response. It is optional when the request instead uses a reusable `prompt` or continues a stored response with `previous_response_id`.

  Each item can be:

  * `message`: A conversation message with role and content
  * `function_call`: A function call request
  * `function_call_output`: Output from a function call

  For multimodal input, `message.content` can be either a plain string or an array of content blocks. For image-capable models such as GPT-5.4 variants, pass images as `input_image` blocks instead of embedding URLs or Base64 strings directly into plain text.

  Example content blocks:

  * `{ "type": "input_text", "text": "Describe this image" }`
  * `{ "type": "input_image", "image_url": "https://example.com/image.jpg" }`
  * `{ "type": "input_image", "image_url": "data:image/png;base64,..." }`
</ParamField>

<ParamField body="instructions" type="string">
  System instructions for the model (equivalent to system message).
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  Maximum number of tokens to generate.
</ParamField>

<ParamField body="temperature" type="number" default="1">
  Sampling temperature between 0 and 2.
</ParamField>

<ParamField body="tools" type="array">
  A list of tools the model may call. AI Sonar forwards native tool definitions without maintaining a local hosted-tool whitelist; the selected service decides which types and combinations are supported.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  If true, returns a stream of events.
</ParamField>

<ParamField body="previous_response_id" type="string">
  ID of a previous response to continue the conversation from.
</ParamField>

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

<ParamField body="background" type="boolean" default="false">
  Whether to ask the selected native Responses service to run asynchronously. AI Sonar does not infer support from the provider or model name: a clear service rejection is returned unchanged, while an accepted queued or in-progress response remains trackable until it reaches a terminal state, even if the client never retrieves it.
</ParamField>

<ParamField body="prompt" type="object">
  Reference to a reusable prompt template and variables.
</ParamField>

<ParamField body="metadata" type="object">
  Metadata to attach to the response for tracking purposes.
</ParamField>

<ParamField body="text" type="object">
  Text generation configuration options. Behavior for `text.format` depends on the selected model and routed path; it is not guaranteed uniformly across every model.
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean" default="true">
  Whether to allow multiple tool calls in parallel.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling parameter (0-1).
</ParamField>

<ParamField body="reasoning" type="object">
  Reasoning configuration for reasoning-enabled models such as GPT-5 family variants.

  * `effort` (string): Reasoning effort level (`low`, `medium`, `high`)
</ParamField>

## Response

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

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

<ResponseField name="created_at" type="integer">
  Unix timestamp of when the response was created.
</ResponseField>

<ResponseField name="output" type="array">
  List of output items generated by the model.
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics.
</ResponseField>

Valid response states include `queued`, `in_progress`, `completed`, `incomplete`, `failed`, and `cancelled`. An HTTP 200 response whose native status is `failed` or `incomplete` is returned as-is; it is not rewritten to a gateway 502.

## Lifecycle boundaries

* `GET /v1/responses/{id}` retrieves the stored response and supports `include`, `include_obfuscation`, `stream`, and `starting_after`.
* `DELETE /v1/responses/{id}` deletes a stored response. It is not a cancellation endpoint.
* `POST /v1/responses/compact` returns the native `response.compaction` contract.
* Public cancel, input-items, and input-tokens endpoints are not currently exposed.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.aisonar.dev/v1/responses" \
    -H "Authorization: Bearer sk-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "input": [
        {"type": "message", "role": "user", "content": "Hello!"}
      ],
      "max_output_tokens": 1000
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-your-api-key",
      base_url="https://api.aisonar.dev/v1"
  )

  response = client.responses.create(
      model="gpt-4o",
      input=[
          {"type": "message", "role": "user", "content": "Hello!"}
      ],
      max_output_tokens=1000
  )

  print(response.output)
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    apiKey: 'sk-your-api-key',
    baseURL: 'https://api.aisonar.dev/v1'
  });

  const response = await client.responses.create({
    model: 'gpt-4o',
    input: [
      { type: 'message', role: 'user', content: 'Hello!' }
    ],
    max_output_tokens: 1000
  });

  console.log(response.output);
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      payload := map[string]interface{}{
          "model": "gpt-4o",
          "input": []map[string]interface{}{
              {"type": "message", "role": "user", "content": "Hello!"},
          },
          "max_output_tokens": 1000,
      }
      body, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", "https://api.aisonar.dev/v1/responses", bytes.NewBuffer(body))
      req.Header.Set("Authorization", "Bearer sk-your-api-key")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      var result map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&result)
      fmt.Println(result["output"])
  }
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.aisonar.dev/v1/responses');

  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Content-Type: application/json',
          'Authorization: Bearer sk-your-api-key'
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'model' => 'gpt-4o',
          'input' => [
              ['type' => 'message', 'role' => 'user', 'content' => 'Hello!']
          ],
          'max_output_tokens' => 1000
      ])
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data['output']);
  ```

  ## Vision Input Example

  Use image-capable models by placing images inside `message.content` as `input_image` blocks. The `image_url` value can be either a public URL or a Base64 data URL.

  ```json theme={null}
  {
    "model": "gpt-5.4",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Please describe this image."
          },
          {
            "type": "input_image",
            "image_url": "https://example.com/demo.jpg"
          }
        ]
      }
    ]
  }
  ```

  ```json theme={null}
  {
    "model": "gpt-5.4",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Please describe this image."
          },
          {
            "type": "input_image",
            "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
          }
        ]
      }
    ]
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "resp_abc123",
    "object": "response",
    "created": 1706000000,
    "model": "gpt-4o",
    "output": [
      {
        "type": "message",
        "role": "assistant",
        "content": [
          {"type": "text", "text": "Hello! How can I help you today?"}
        ]
      }
    ],
    "usage": {
      "input_tokens": 10,
      "output_tokens": 12,
      "total_tokens": 22
    }
  }
  ```
</ResponseExample>