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

# 创建响应

> 使用文本输入、工具、推理控制、流式传输与多轮延续创建模型响应。

从文本或结构化输入创建响应。Responses API 将输出表示为类型化 Item，适合新的 Agent 工作流。

## 端点

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://api.yelu.ai/v1/responses
```

## 请求头

<ParamField header="Authorization" type="string" required>格式为 `Bearer $YELU_API_KEY`。</ParamField>
<ParamField header="Content-Type" type="string" required>必须为 `application/json`。</ParamField>

## 请求体

<ParamField body="model" type="string" required>[模型列表](/zh/api-reference/models)返回的模型 ID。</ParamField>
<ParamField body="input" type="string | array">文本，或类型化输入消息/Item 数组。</ParamField>
<ParamField body="instructions" type="string">本次响应的高优先级指令。</ParamField>
<ParamField body="previous_response_id" type="string">兼容模型/供应商支持时，用于延续先前响应。</ParamField>
<ParamField body="max_output_tokens" type="integer">最大输出 Token，包括模型特定推理用量。</ParamField>
<ParamField body="temperature" type="number">支持该控制的模型使用的采样温度。</ParamField>
<ParamField body="top_p" type="number">支持该控制的模型使用的核采样概率。</ParamField>
<ParamField body="stream" type="boolean" default="false">设为 `true` 时返回类型化 SSE Event。</ParamField>
<ParamField body="tools" type="array">模型可以调用的工具定义。</ParamField>
<ParamField body="tool_choice" type="string | object">控制是否以及选择哪个工具。</ParamField>
<ParamField body="reasoning" type="object">推理配置，可包含 `effort` 和供应商支持的摘要控制。</ParamField>
<ParamField body="truncation" type="string" default="disabled">`auto` 允许自动截断；`disabled` 会在上下文过长时失败。</ParamField>

## 响应

<ResponseField name="id" type="string" required>响应唯一 ID。</ResponseField>
<ResponseField name="object" type="string" required>完整响应固定为 `response`。</ResponseField>
<ResponseField name="created_at" type="integer" required>Unix 创建时间戳。</ResponseField>
<ResponseField name="status" type="string" required>`completed`、`failed`、`in_progress` 或 `incomplete`。</ResponseField>
<ResponseField name="model" type="string" required>处理请求的模型。</ResponseField>
<ResponseField name="output" type="array" required>类型化输出 Item；消息、文本和工具调用分别表示。</ResponseField>
<ResponseField name="usage" type="object">输入、输出、缓存或推理 Token 用量。</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl https://api.yelu.ai/v1/responses \
    -H "Authorization: Bearer $YELU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"gpt-4o-mini","instructions":"面向软件工程师回答。","input":"什么是幂等性？","max_output_tokens":160}'
  ```

  ```javascript JavaScript (Fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.yelu.ai/v1/responses', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.YELU_API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      model: 'gpt-4o-mini',
      instructions: '面向软件工程师回答。',
      input: '什么是幂等性？',
      max_output_tokens: 160,
    }),
  });
  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  console.log(data.output.flatMap((item) => item.content ?? []).filter((part) => part.type === 'output_text').map((part) => part.text).join(''));
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.post(
      "https://api.yelu.ai/v1/responses",
      headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
      json={"model": "gpt-4o-mini", "instructions": "面向软件工程师回答。", "input": "什么是幂等性？", "max_output_tokens": 160},
      timeout=60,
  )
  response.raise_for_status()
  data = response.json()
  print("".join(part["text"] for item in data["output"] for part in item.get("content", []) if part.get("type") == "output_text"))
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id":"resp_01JYELU9R2","object":"response","created_at":1783900800,"status":"completed","model":"gpt-4o-mini",
    "output":[{"type":"message","id":"msg_01JYELU9R3","status":"completed","role":"assistant","content":[{"type":"output_text","text":"幂等性表示同一操作重复执行时，预期效果与执行一次相同。"}]}],
    "usage":{"input_tokens":20,"output_tokens":22,"total_tokens":42}
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {"error":{"message":"Input is required for this request.","type":"invalid_request_error","param":"input","code":"missing_required_parameter"}}
  ```
</ResponseExample>

## 错误码

| 状态码         | 含义                    |
| ----------- | --------------------- |
| `400`       | 输入 Item、字段、工具或模型能力无效  |
| `401`       | Key 缺失或无效             |
| `403`       | 无权使用模型或操作             |
| `404`       | 模型或先前 Response ID 不存在 |
| `413`       | 输入超过请求或上下文限制          |
| `429`       | 达到请求限制                |
| `500`–`504` | 网关或上游临时失败             |

<Warning>不同供应商对服务端响应状态的支持不同。请自行持久化应用需要的对话状态，不要只依赖 `previous_response_id`。</Warning>