章節導覽

Responses API

相容 OpenAI Responses API 格式的端點，支援無狀態多輪對話、工具呼叫與多模態輸入。適用於使用 OpenAI Python SDK ≥ 1.x 的 client.responses.create() 的 Agent 框架。

POST/v1/responses

Note

使用與 Chat Completions 相同的身份驗證與模型路由邏輯。

請求內文

model必填

string

使用 GET /v1/models 列出的 id 或 alias，例如「claude-sonnet-4.6」或「anthropic/claude-sonnet-4.6」。

input必填

string | Item[]

使用者輸入 — 純字串（單則訊息）或輸入項目陣列（多輪 / 多模態對話）。

instructions

string

系統層級指令，等同於 system 角色的訊息。每次請求都必須重新傳送。

stream

boolean

若為 true，回傳 Responses API SSE 串流事件，包含 response.created、response.output_text.delta、response.completed 等事件類型。

max_output_tokens

integer

最大輸出 Token 數量（o 系列推理模型包含推理 Token）。

temperature

number

取樣參數會轉送且不做範圍驗證；模型可能自行限制或忽略超出支援範圍的值。

top_p

number

核取樣概率質量。預設：1

tools

Tool[]

工具（函式）定義，格式與 Chat Completions 相同的 JSON Schema（接受扁平的 Responses 格式，也接受巢狀格式）。不支援 OpenAI 專屬的內建託管工具（web_search_preview、file_search、computer_use_preview）；網頁搜尋可透過 plugins: [{id:"web"}] 啟用，僅部分模型路由支援。

tool_choice

string | object

控制工具使用："auto"、"none" 或指定工具

parallel_tool_calls

boolean

啟用並行工具呼叫功能。預設：true。僅限 OpenAI 系列模型 —— 見下方說明。

response_format

object

強制結構化 JSON 輸出。請參閱結構化輸出章節

previous_response_id

string

本端點是無狀態的——傳入非 null 值會直接回 400（invalid_prompt），不是被接受後忽略。請改用無狀態模式：在 input 陣列中帶入完整對話歷史。

請求結構 (TypeScript)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
type ResponsesRequest = {
  model: string;                    // Listed id or alias from GET /v1/models
  input: string | InputItem[];      // string or multi-turn array

  // Optional
  instructions?: string;            // System-level message
  stream?: boolean;                 // Default: false
  max_output_tokens?: number;
  temperature?: number;
  top_p?: number;
  tools?: Tool[];
  tool_choice?: "auto" | "none" | "required" | object;
  parallel_tool_calls?: boolean;    // Default: true
  previous_response_id?: string;    // Not supported — use full input array
};

type InputItem =
  | { type?: "message"; role: "user" | "assistant" | "system" | "developer"; content: string | ContentBlock[] }
  | { type: "function_call_output"; call_id: string; output: string }   // tool result
  | { type: "function_call"; call_id: string; name: string; arguments: string };

type ContentBlock =
  | { type: "input_text"; text: string }
  | { type: "input_image"; image_url: string; detail?: "auto" | "low" | "high" };

範例請求

1
2
3
4
5
6
7
8
curl https://api.bazaarlink.ai/v1/responses \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "instructions": "You are a helpful assistant.",
    "input": "What is the capital of Taiwan?"
  }'

回應格式

BazaarLink 回傳標準化回應，並移除上游專屬欄位。回應中不透明的 BazaarLink 請求 ID 與 x-request-id 相同；可搭配 GET /v1/generation 使用。非串流回應也會在 x-generation-id 回傳同一個 ID。usage.cost 是向客戶收取的美元金額。統計資料可能在完成後數秒才可用；若收到 404，請稍後短暫重試。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// Non-streaming response object
type ResponsesResponse = {
  id: string;             // Opaque BazaarLink request id; format may change
  object: "response";
  created_at: number;
  completed_at: number;
  status: "completed" | "failed" | "incomplete";
  model: string;
  output: OutputItem[];
  usage: {
    input_tokens: number;   // equivalent to prompt_tokens
    output_tokens: number;  // equivalent to completion_tokens
    total_tokens: number;
    cost?: number;          // USD amount charged to the customer for this request
  } | null;
  error: null | { code: string; message: string };
};

type OutputItem =
  | {
      type: "message";
      id: string;
      role: "assistant";
      status: "completed";
      content: Array<{ type: "output_text"; text: string; annotations: [] }>;
    }
  | { type: "function_call"; id: string; call_id: string; name: string; arguments: string; status: "completed" };

從 Chat Completions 遷移

將 messages 改為 input（字串或陣列），以 instructions 取代 system 角色訊息，並從 output[0].content[0].text 讀取回應內容（原為 choices[0].message.content）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Chat Completions (before)
response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[
        {"role": "system", "content": "You are helpful."},
        {"role": "user",   "content": "Hello"},
    ]
)
text = response.choices[0].message.content

# Responses API (after)
response = client.responses.create(
    model="openai/gpt-5.4-mini",
    instructions="You are helpful.",
    input="Hello"
)
text = response.output[0].content[0].text

限制事項

previous_response_id 或 store: true 會被拒絕並回傳 400（錯誤碼 invalid_prompt）——不是被接受後忽略。請一律使用無狀態模式，在 input 陣列中帶入完整對話歷史。
不支援 OpenAI 專屬的內建託管工具（web_search_preview、file_search、computer_use_preview）。網頁搜尋可透過 plugins: [{id:"web"}] 啟用，僅部分模型路由支援。
background: true 會被接受但忽略，請求一律同步執行到完成為止。