# Responses API

> LLMoxy POST /v1/responses 的請求欄位、預設過濾，以及 grok-4.6 與 grok-4.7 的流式實測。

`POST https://llmoxy.com/v1/responses` 接收 JSON 請求。請求頭：

```txt
Authorization: Bearer <LLMOXY_API_KEY>
Content-Type: application/json
```

閘道把正文解析成固定結構。`model` 為空，或正文裡沒有 `input`，請求會被拒絕。`max_output_tokens` 大於 1,073,741,823 時也會被拒絕。`background` 不在這個結構裡。

沒有打開請求體透傳時，只保留下表欄位，並預設去掉 `service_tier`、`safety_identifier` 和 `stream_options.include_obfuscation`。`store` 預設保留。可空數字寫成 `0`、`stream` 寫成 `false` 時仍會發出。`stream_options` 裡的布林值在重新組包時，`false` 會被省略。表以外的欄位不會發出。

## 請求欄位

| 欄位 | 類型 | 必填 | 閘道行為 |
| --- | --- | --- | --- |
| `model` | string | 是 | 非空模型 ID。 |
| `input` | string 或 array | 是 | 必須出現。字串按一段輸入文字計。陣列元素可帶 `role`。`content` 為字串時按輸入文字計；為陣列時識別 `input_text`、`input_image`、`input_file`。`image_url` 和 `file_url` 可以是字串，或帶 `url` 的物件。 |
| `include` | JSON | 否 | 原樣保留。 |
| `conversation` | JSON | 否 | 原樣保留。 |
| `context_management` | JSON | 否 | 原樣保留。 |
| `instructions` | JSON | 否 | 原樣保留。常見寫法是字串。 |
| `max_output_tokens` | number | 否 | 可空。顯式 `0` 會保留。 |
| `top_logprobs` | number | 否 | 可空。顯式 `0` 會保留。 |
| `metadata` | JSON | 否 | 原樣保留。 |
| `parallel_tool_calls` | JSON | 否 | 原樣保留。顯式 `false` 會保留。 |
| `previous_response_id` | string | 否 | 空字串省略。 |
| `reasoning.effort` | string | 否 | 空字串省略。閘道不校驗取值。 |
| `reasoning.summary` | string | 否 | 空字串省略。閘道不校驗取值。 |
| `service_tier` | string | 否 | 預設去掉。 |
| `store` | JSON | 否 | 預設保留。顯式 `false` 會保留。 |
| `prompt_cache_key` | JSON | 否 | 原樣保留。 |
| `prompt_cache_retention` | JSON | 否 | 原樣保留。 |
| `safety_identifier` | JSON | 否 | 預設去掉。 |
| `stream` | boolean | 否 | 缺省按非流式處理。顯式 `false` 會保留。 |
| `stream_options.include_usage` | boolean | 否 | 重新組包時 `false` 省略。 |
| `stream_options.include_obfuscation` | boolean | 否 | 預設去掉。重新組包時 `false` 省略。 |
| `temperature` | number | 否 | 可空。顯式 `0` 會保留。 |
| `text` | JSON | 否 | 原樣保留。 |
| `tool_choice` | JSON | 否 | 原樣保留。 |
| `tools` | JSON | 否 | 原樣保留。 |
| `top_p` | number | 否 | 可空。顯式 `0` 會保留。 |
| `truncation` | JSON | 否 | 原樣保留。 |
| `user` | JSON | 否 | 原樣保留。 |
| `max_tool_calls` | number | 否 | 可空。顯式 `0` 會保留。 |
| `prompt` | JSON | 否 | 原樣保留。 |
| `enable_thinking` | JSON | 否 | 原樣保留。 |
| `preset` | JSON | 否 | 原樣保留。 |

## grok-4.6 與 grok-4.7

2026-10-03 對 `https://llmoxy.com/v1/responses` 的流式呼叫裡，`grok-4.6` 和 `grok-4.7` 都返回 HTTP 200，並完成同一組事件。

| 模型 | HTTP | 響應裡的 `model` | `status` | 正文 | input / output / total |
| --- | --- | --- | --- | --- | --- |
| `grok-4.6` | 200 | `grok-4.6` | `completed` | `pong` | 212 / 98 / 310 |
| `grok-4.7` | 200 | `grok-4.7` | `completed` | `pong` | 1248 / 55 / 1303 |

`grok-4.6` 的 `input_tokens_details.cached_tokens` 為 128，`output_tokens_details.reasoning_tokens` 為 97。`grok-4.7` 分別為 1152 和 54。

正文位於 `output` 中 `type` 為 `message` 的項，`content` 裡 `type` 為 `output_text` 的 `text`。兩個模型都會先輸出 `type` 為 `reasoning` 的項。`response.completed` 裡該 reasoning 項的 `status` 仍是 `in_progress`。

當前這兩個模型的請求打開了請求體透傳，所以下一節的最小 JSON 按客戶端原文發出。

## 最小成功請求

`grok-4.6` 使用同一正文，只把 `model` 換成 `grok-4.6`。

```bash
curl https://llmoxy.com/v1/responses \
  -H "Authorization: Bearer <LLMOXY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Reply with exactly: pong",
    "max_output_tokens": 64,
    "stream": true
  }'
```

響應的 `Content-Type` 為 `text/event-stream`。每條事件是一行 `event:` 和一行 `data:`。閘道轉發已解析事件的原始 JSON，事件名取自 JSON 裡的 `type`。結束標記是最後一條 `response.completed`。

兩個模型的事件名順序相同：

`response.created`，`response.in_progress`，`response.output_item.added`，`response.reasoning_summary_part.added`，`response.reasoning_summary_text.delta`，`response.reasoning_summary_text.delta`，`response.reasoning_summary_text.done`，`response.reasoning_summary_part.done`，`response.output_item.done`，`response.output_item.added`，`response.content_part.added`，`response.output_text.delta`，`response.output_text.done`，`response.content_part.done`，`response.output_item.done`，`response.completed`。

下面是 `grok-4.7` 的實測事件。響應 ID 和輸出項 ID 已換成占位符，其餘欄位與當次響應一致。

```txt
event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"object":"response","id":"resp_example","created_at":1791015238,"model":"grok-4.7","output":[],"status":"in_progress"},"output_index":0}

event: response.in_progress
data: {"type":"response.in_progress","sequence_number":1,"response":{"object":"response","id":"resp_example","created_at":1791015238,"model":"grok-4.7","output":[],"status":"in_progress"},"output_index":0}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":2,"output_index":0,"item":{"id":"item_reasoning","type":"reasoning","status":"in_progress","summary":[]}}

event: response.reasoning_summary_part.added
data: {"type":"response.reasoning_summary_part.added","sequence_number":3,"output_index":0,"item_id":"item_reasoning","part":{"type":"summary_text","text":""},"summary_index":0}

event: response.reasoning_summary_text.delta
data: {"type":"response.reasoning_summary_text.delta","sequence_number":4,"output_index":0,"item_id":"item_reasoning","delta":"The user wants a reply","summary_index":0}

event: response.reasoning_summary_text.delta
data: {"type":"response.reasoning_summary_text.delta","sequence_number":5,"output_index":0,"item_id":"item_reasoning","delta":" of exactly \"pong\".","summary_index":0}

event: response.reasoning_summary_text.done
data: {"type":"response.reasoning_summary_text.done","sequence_number":6,"output_index":0,"item_id":"item_reasoning","text":"The user wants a reply of exactly \"pong\".","summary_index":0}

event: response.reasoning_summary_part.done
data: {"type":"response.reasoning_summary_part.done","sequence_number":7,"output_index":0,"item_id":"item_reasoning","part":{"type":"summary_text","text":"The user wants a reply of exactly \"pong\"."},"summary_index":0}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":8,"output_index":0,"item":{"id":"item_reasoning","type":"reasoning","summary":[{"text":"The user wants a reply of exactly \"pong\".","type":"summary_text"}]}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":9,"output_index":1,"item":{"id":"item_message","type":"message","role":"assistant","content":[],"status":"in_progress"}}

event: response.content_part.added
data: {"type":"response.content_part.added","sequence_number":10,"output_index":1,"item_id":"item_message","content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":11,"output_index":1,"item_id":"item_message","content_index":0,"delta":"pong"}

event: response.output_text.done
data: {"type":"response.output_text.done","sequence_number":12,"output_index":1,"item_id":"item_message","content_index":0,"text":"pong"}

event: response.content_part.done
data: {"type":"response.content_part.done","sequence_number":13,"output_index":1,"item_id":"item_message","content_index":0,"part":{"type":"output_text","text":"pong","annotations":[]}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":14,"output_index":1,"item":{"id":"item_message","type":"message","role":"assistant","content":[{"type":"output_text","annotations":[],"text":"pong"}],"status":"completed"}}

event: response.completed
data: {"type":"response.completed","sequence_number":15,"response":{"object":"response","id":"resp_example","created_at":1791015238,"model":"grok-4.7","output":[{"id":"item_reasoning","type":"reasoning","status":"in_progress","summary":[{"text":"The user wants a reply of exactly \"pong\".","type":"summary_text"}]},{"id":"item_message","type":"message","role":"assistant","content":[{"type":"output_text","text":"pong"}],"status":"completed"}],"status":"completed","usage":{"input_tokens":1248,"input_tokens_details":{"cached_tokens":1152},"output_tokens":55,"output_tokens_details":{"reasoning_tokens":54},"total_tokens":1303}},"output_index":0}
```

## 對話壓縮

```txt
POST https://llmoxy.com/v1/responses/compact
```

請求欄位是 `model`（必填）、`input`、`instructions`、`previous_response_id`。上面的 grok 實測沒有呼叫這個路由。

本文是 https://tw.llmoxy.com/docs/api-reference/responses 的 markdown 版本。
