> ## 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

使用 OpenAI Responses API 格式创建流式或非流式响应。

## 认证

<ParamField header="Authorization" type="string" required>
  Bearer 令牌。在 Authorization 请求头中使用您的 API 密钥作为 Bearer 令牌。

  格式：`Bearer <SUNRA_KEY>`
</ParamField>

## 请求

此端点接受一个 JSON 对象。

<ParamField body="model" type="string" required>
  用于生成响应的模型 ID。在 [sunra.ai/models](https://sunra.ai/models) 浏览可用模型。
</ParamField>

<ParamField body="provider" type="object">
  可选的 Provider 路由偏好。省略时使用自动路由。支持的字段和 Provider 查询方式见 [Provider 路由](/zh-Hans/llm/provider-routing)。
</ParamField>

<ParamField body="input" type="string | object[]">
  响应请求的输入。可以是字符串或输入项数组。

  <Expandable title="属性（数组时）">
    <ParamField body="type" type="string">
      输入项的类型。支持的值：`message`、`item_reference`。
    </ParamField>

    <ParamField body="role" type="string">
      消息作者的角色。支持的值：`user`、`assistant`、`system`。
    </ParamField>

    <ParamField body="content" type="string | object[]">
      输入消息的内容。可以是字符串或内容部分数组。
    </ParamField>

    <ParamField body="id" type="string">
      项目的 ID。对话历史中的 `assistant` 消息必填。
    </ParamField>

    <ParamField body="status" type="string">
      项目的状态。对话历史中的 `assistant` 消息必填。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="instructions" type="string | null">
  在模型上下文的第一个项目中插入系统（或开发者）消息。与 `input` 一起使用时，指令会插入到输入的开头。
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  如果设置为 `true`，将使用服务器发送事件（SSE）流式传输响应。流式请求受空闲超时与生命周期上限约束，见[输出上限与流生命周期](/zh-Hans/llm/limits#流生命周期)。
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  输出令牌数的上限，包括可见输出令牌和推理令牌。超过模型自身上限的值会返回 `400`，而不会被静默削平。见[输出上限](/zh-Hans/llm/limits)。
</ParamField>

<ParamField body="temperature" type="number" default={1}>
  采样温度，介于 0 到 2 之间。较高的值增加随机性。
</ParamField>

<ParamField body="top_p" type="number" default={1}>
  核采样参数。温度采样的替代方案。
</ParamField>

<ParamField body="frequency_penalty" type="number" default={0}>
  介于 -2.0 和 2.0 之间的数字。正值会根据新令牌在文本中的现有频率进行惩罚。
</ParamField>

<ParamField body="presence_penalty" type="number" default={0}>
  介于 -2.0 和 2.0 之间的数字。正值会根据新令牌是否已出现在文本中进行惩罚。
</ParamField>

<ParamField body="tools" type="object[]">
  模型可以调用的工具数组。

  <Expandable title="属性">
    <ParamField body="type" type="string" required>
      工具的类型。支持的值：`function`、`web_search_preview`。
    </ParamField>

    <ParamField body="name" type="string">
      函数的名称。当类型为 `function` 时必填。
    </ParamField>

    <ParamField body="description" type="string">
      函数的描述。
    </ParamField>

    <ParamField body="parameters" type="object">
      定义函数参数的 JSON Schema 对象。
    </ParamField>

    <ParamField body="strict" type="boolean" default={false}>
      是否启用严格的 schema 遵循。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="string | object">
  控制工具选择行为。支持的字符串值：`none`、`auto`、`required`。也可以指定特定函数。
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean" default={true}>
  是否允许模型并行运行工具调用。
</ParamField>

<ParamField body="text" type="object">
  文本响应格式的配置。

  <Expandable title="属性">
    <ParamField body="format" type="object">
      文本格式配置。

      <Expandable title="属性">
        <ParamField body="type" type="string" required>
          格式类型。支持的值：`text`、`json_object`、`json_schema`。
        </ParamField>

        <ParamField body="name" type="string">
          响应格式的名称。当类型为 `json_schema` 时必填。
        </ParamField>

        <ParamField body="schema" type="object">
          JSON Schema。当类型为 `json_schema` 时必填。
        </ParamField>

        <ParamField body="strict" type="boolean">
          是否启用严格的 schema 遵循。
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="reasoning" type="object">
  推理输出的配置。

  <Expandable title="属性">
    <ParamField body="effort" type="string">
      约束推理的工作量。支持的值：`low`、`medium`、`high`。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="store" type="boolean" default={true}>
  是否存储生成的响应以供后续检索。
</ParamField>

<ParamField body="metadata" type="object">
  可附加到响应的 16 个键值对集合。键为最长 64 个字符的字符串。值为最长 512 个字符的字符串。
</ParamField>

<ParamField body="user" type="string">
  代表您的最终用户的唯一标识符。最长 128 个字符。
</ParamField>

## 响应

成功的响应对象。

<ResponseField name="id" type="string">
  唯一响应标识符。
</ResponseField>

<ResponseField name="object" type="string">
  对象类型。始终为 `response`。
</ResponseField>

<ResponseField name="created_at" type="number">
  响应创建时的 Unix 时间戳（秒）。
</ResponseField>

<ResponseField name="status" type="string">
  响应的状态。可能的值：`completed`、`failed`、`in_progress`、`cancelled`。
</ResponseField>

<ResponseField name="model" type="string">
  用于生成响应的模型。
</ResponseField>

<ResponseField name="output" type="object[]">
  模型生成的内容项数组。

  <Expandable title="属性">
    <ResponseField name="type" type="string">
      输出项的类型。例如 `message`。
    </ResponseField>

    <ResponseField name="id" type="string">
      输出项的唯一 ID。
    </ResponseField>

    <ResponseField name="role" type="string">
      角色。始终为 `assistant`。
    </ResponseField>

    <ResponseField name="status" type="string">
      消息的状态。例如 `completed`。
    </ResponseField>

    <ResponseField name="content" type="object[]">
      输出消息的内容。

      <Expandable title="属性">
        <ResponseField name="type" type="string">
          内容类型。例如 `output_text`。
        </ResponseField>

        <ResponseField name="text" type="string">
          生成的文本内容。
        </ResponseField>

        <ResponseField name="annotations" type="object[]">
          内容的注释（例如来自网页搜索的引用）。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  响应的令牌使用统计。

  <Expandable title="属性">
    <ResponseField name="input_tokens" type="integer">
      输入令牌数。
    </ResponseField>

    <ResponseField name="output_tokens" type="integer">
      输出令牌数。
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      总令牌数。
    </ResponseField>

    <ResponseField name="input_tokens_details" type="object">
      输入令牌明细。

      <Expandable title="属性">
        <ResponseField name="cached_tokens" type="integer">
          缓存令牌数。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="output_tokens_details" type="object">
      输出令牌明细。

      <Expandable title="属性">
        <ResponseField name="reasoning_tokens" type="integer">
          推理令牌数。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="temperature" type="number">
  使用的采样温度。
</ResponseField>

<ResponseField name="top_p" type="number">
  使用的核采样值。
</ResponseField>

<ResponseField name="max_output_tokens" type="integer | null">
  使用的最大输出令牌数设置。
</ResponseField>

<ResponseField name="error" type="object | null">
  如果生成失败，则为错误对象。
</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,
    "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": []
          }
        ]
      }
    ],
    "temperature": 1.0,
    "top_p": 1.0,
    "max_output_tokens": null,
    "usage": {
      "input_tokens": 15,
      "output_tokens": 18,
      "total_tokens": 33,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens_details": {
        "reasoning_tokens": 0
      }
    },
    "error": null
  }
  ```
</ResponseExample>