OpenAI Responses API

透過 AIXHUB 以 Bearer 驗證傳送非串流與串流 Responses 請求，並使用明確完成條件與有限重試。

AIXHUB 提供 OpenAI 相容 Responses 路由。Base URL 使用 https://api.aixhub.org/v1，或直接以 HTTP POST 呼叫完整端點 https://api.aixhub.org/v1/responses。驗證標頭使用 Authorization: Bearer <AIXHUB API key>，模型則使用 panel-model-id 等完整相容 ID。

POSThttps://api.aixhub.org/v1/responses

請先依照 API 驗證建立專用金鑰，從模型路由複製模型 ID，並避免把真實金鑰放入原始碼、命令歷程、螢幕擷取畫面與記錄。

請求欄位

最小請求使用以下公開 Responses 欄位：

欄位	類型	必要	本指南用法
`model`	字串	是	完整 AIXHUB 模型 ID：`panel-model-id`
`input`	字串或輸入項目陣列	是	範圍明確的指令；範例使用字串
`instructions`	字串	否	應用程式需要時使用的較高層回應指令
`stream`	布林值	否	設為 `true` 以接收 Server-Sent Events

不要把 Chat Completions 的 messages 主體送到這個端點。最小請求成功且所選路由支援後，才加入選用工具、對話狀態、結構化文字設定或 Token 限制。

設定暫時環境變數

Bash 請以不回顯方式讀取金鑰，避免把真實值留在 Shell 歷程：

read -r -s -p "AIXHUB API key: " AIXHUB_KEY
printf '\n'
export AIXHUB_API_KEY="$AIXHUB_KEY"
unset AIXHUB_KEY
export AIXHUB_MODEL="panel-model-id"

Windows PowerShell 請使用 SecureString 輸入，明文只放在目前工作階段的環境變數：

$secureKey = Read-Host "AIXHUB API key" -AsSecureString
$plainKey = [System.Net.NetworkCredential]::new("", $secureKey).Password
$env:AIXHUB_API_KEY = $plainKey
$env:AIXHUB_MODEL = "panel-model-id"
Remove-Variable plainKey, secureKey

測試完成後關閉終端機，即可清除工作階段環境。排錯時不可顯示 AIXHUB_API_KEY。

Bash 最小請求

curl --fail-with-body --silent --show-error \
  --request POST \
  --url "https://api.aixhub.org/v1/responses" \
  --header "Authorization: Bearer $AIXHUB_API_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "model": "$AIXHUB_MODEL",
  "input": "Reply with OK only."
}
JSON

PowerShell 最小請求

$body = @{
  model = $env:AIXHUB_MODEL
  input = "Reply with OK only."
} | ConvertTo-Json

$request = @{
  Method = "Post"
  Uri = "https://api.aixhub.org/v1/responses"
  Headers = @{ Authorization = "Bearer $($env:AIXHUB_API_KEY)" }
  ContentType = "application/json"
  Body = $body
}

$response = Invoke-RestMethod @request
$response | ConvertTo-Json -Depth 20

$text = @(
  $response.output |
    Where-Object { $_.type -eq "message" } |
    ForEach-Object { $_.content } |
    Where-Object { $_.type -eq "output_text" } |
    Select-Object -ExpandProperty text
) -join ""
$text

兩種 Shell 使用相同請求主體與 Authorization 標頭。請保留 HTTP 狀態、回應主體，以及伺服器實際回傳的回應標頭；分享診斷內容前，先移除憑證與使用者輸入。

回應範例

以下是使用 OpenAI 公開欄位形狀的完整代表性非串流 Responses 物件。實際回應中的 ID、時間戳、Token 數、預設值與選用欄位可能不同；此範例不主張任何 AIXHUB 專屬回應欄位。

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1780000000,
  "status": "completed",
  "background": false,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "panel-model-id",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "text": "OK"
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 2,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 14
  },
  "user": null,
  "metadata": {}
}

只有 status: "completed" 代表成功完成。狀態為 failed 時檢查 error；狀態為 incomplete 時檢查 incomplete_details，不可把部分輸出當成完整結果。

output 陣列可能含有不同類型的項目。不要假設 output[0].content[0] 一定是文字。請依序檢查輸出項目，找出助手訊息中 type: "output_text" 的內容，再串接其中的文字。官方 SDK 可能提供 output_text 便利存取方式；原始 HTTP 用戶端則要檢查完整物件。usage 只有實際存在時才使用。

Response 物件 ID 是不透明識別值。請求 ID 屬於 HTTP 回應標頭，不在這個 JSON 範例中。

串流

將 stream 設為 true，並以 Server-Sent Events 處理回應。端點與 Bearer 驗證方式不變。

Bash SSE 請求

curl --no-buffer --fail-with-body --silent --show-error \
  --request POST \
  --url "https://api.aixhub.org/v1/responses" \
  --header "Authorization: Bearer $AIXHUB_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: text/event-stream" \
  --data @- <<JSON
{
  "model": "$AIXHUB_MODEL",
  "input": "Reply with OK only.",
  "stream": true
}
JSON

PowerShell SSE 請求

在 PowerShell 內使用 curl.exe，讓事件抵達時立即顯示：

$streamBody = @{
  model = $env:AIXHUB_MODEL
  input = "Reply with OK only."
  stream = $true
} | ConvertTo-Json -Compress

$streamBody | curl.exe --no-buffer --fail-with-body --silent --show-error --request POST --url "https://api.aixhub.org/v1/responses" --header "Authorization: Bearer $($env:AIXHUB_API_KEY)" --header "Content-Type: application/json" --header "Accept: text/event-stream" --data-binary "@-"

請處理以下公開 Responses 事件類型：

事件	意義	用戶端動作
`response.created`	Response 物件已建立	事件內容實際提供時，保留其中的 Response ID
`response.in_progress`	正在產生回應	繼續讀取；這不是結束成功
`response.output_text.delta`	收到文字片段	依事件順序附加 `delta`
`response.completed`	結束成功	完成文字組合並檢查完整 Response
`response.failed`	結束失敗	捨棄或標記部分輸出，並檢查 `error`
`response.incomplete`	結束但不完整	將輸出標示為不完整，並檢查 `incomplete_details`
`error`	串流終止錯誤	停止讀取、保留移除敏感資訊後的錯誤內容，且不可採用部分輸出

HTTP 200 及一個以上 delta 事件都不能證明成功。必須等待且只接受一個結束結果：response.completed、response.failed、response.incomplete 或 error；只有 response.completed 是成功。連線關閉但沒有結束事件時，結果仍不明確，不可回報為完成。

只有 HTTP 回應實際包含 x-request-id 等請求 ID 標頭時才保留。請儲存伺服器回傳的精確標頭名稱和值，不要自行產生 ID。同樣地，只有結束 Response 物件實際包含用量欄位時才讀取。

錯誤與重試

決定是否重試前，先保留 HTTP 狀態、移除敏感資訊後的錯誤主體與回應標頭：

結果	一般處理方式
400	修正請求主體或不支援欄位；不要原樣重試
401	修正 Bearer 金鑰；不要原樣重試
403	解決存取、政策、訂閱或餘額條件；原因改變前不要重試
404	修正端點或重複 `/v1`；不要原樣重試
429	降低速率或並行數；可考慮有限重試
500、502、503、504	可能是暫時性錯誤，但只有明確處理重複風險時才重試
HTTP 200 後的 `response.failed` 或 `response.incomplete`	將串流視為失敗或不完整；不可把部分文字改判為成功
HTTP 200 後的 `error`	將串流視為失敗、保留移除敏感資訊後的內容，並停止讀取

採用保守的重試邊界：

自動重試使用小型總嘗試額度，例如包含原始請求在內最多三次。
回應實際包含 Retry-After 時，遵守該回傳值。若沒有此標頭，使用有上限的指數退避與隨機抖動；不要虛構伺服器指定等待時間。
400、401、403 或 404 不可使用相同請求自動重試。
建立 Responses 可能執行非冪等且會計費的產生工作。逾時、斷線、不明確 5xx 或已接收部分串流後盲目重送，可能造成重複輸出與費用。
只有應用程式明確接受重複結果，或具備自己的關聯與去重政策時，才能重試結果不明確的請求；否則應顯示不確定狀態供人工檢查。

不可記錄 Bearer Token。HTTP 回應實際提供請求 ID 標頭時，聯絡支援可附上該診斷識別值，但仍要移除其他敏感資訊。AIXHUB 狀態處理請繼續參考錯誤代碼。

驗證

從非串流 Response 擷取助手 output_text，或在串流收到 response.completed 後，預期文字為：

OK

確認以下各項：

HTTP 請求完成，且沒有錯誤狀態。
Response 物件或結束事件回報 status: "completed"。
串接後的助手 output_text 是 OK。
AIXHUB 用量在相同時間出現 panel-model-id 且狀態成功的請求。只有用量實際顯示 API 模式時才核對。
回應實際提供請求 ID 標頭時才保留；沒有此標頭時，不要自行建立。

測試結束後清除暫存憑證：

unset AIXHUB_API_KEY AIXHUB_MODEL

Remove-Item Env:AIXHUB_API_KEY, Env:AIXHUB_MODEL -ErrorAction SilentlyContinue
Remove-Variable request, body, response, text, streamBody, secureKey -ErrorAction SilentlyContinue

Responses 請求完成，助手輸出為 OK，且 AIXHUB 用量留下時間、模型與成功狀態相符的記錄。

應用程式程式碼請繼續閱讀 OpenAI SDK 指南。若要使用持續維護的 Responses 用戶端，請參考 Codex CLI。

官方資料

官方連結定義 OpenAI 公開 Responses 合約；AIXHUB Base URL、Bearer 驗證、模型路由及用量核對則來自本站整合合約。

最後核對：2026-07-14

OpenAI Responses API

本頁目錄