文字
建立回應 (Create Response)
使用 OpenAI Responses API 格式建立回應
當模型的 accepted_request_formats 包含 openai_responses 時,請使用此端點。請求與回應將使用 Responses API 格式且不會被轉換:若模型不支援該格式,此處會回傳 400,因此請改用 Chat Completions。選用欄位與支援的值取決於所選模型。
請求主體 (Request Body)
所使用模型的 ID。請參閱 Models 以查看可用選項。
回應的輸入內容。當請求改為使用可重複使用的 prompt 或透過 previous_response_id 接續儲存的回應時,此欄位為選填。
每個項目都是一個包含 type 的物件。常見類型包括:
message:包含角色與內容的對話訊息function_call:函式呼叫請求function_call_output:函式呼叫的輸出reasoning:來自先前回應的思考項目。請原樣回傳。
其他項目類型取決於所選模型。
對於多模態輸入,message.content 可以是純字串或內容區塊陣列。對於具備影像處理能力的模型,請使用 input_image 區塊傳遞影像,而非直接將 URL 或 Base64 字串嵌入純文字中。
內容區塊範例:
{ "type": "input_text", "text": "描述這張圖片" }{ "type": "input_image", "image_url": "https://example.com/image.jpg" }{ "type": "input_image", "image_url": "data:image/png;base64,..." }
模型的系統指令(等同於系統訊息)。
生成 Token 的最大數量。
取樣溫度。支援的值與預設值取決於所選模型。
模型可能呼叫的工具。支援的類型與組合取決於所選模型。
false若為 true,則回傳事件串流。請參閱 串流 (Streaming)。
用於接續對話的先前回應 ID。該回應必須屬於您的帳戶且仍被儲存;否則請求將回傳 404 並附帶 response_not_found 代碼。請使用產生該回應的模型進行接續。若產生該回應的服務暫時無法使用,請求可能會回傳 503。
true是否儲存回應以供後續檢索及作為 previous_response_id 使用。若設為 false,TokenLab 將不會保留該回應,且 GET /v1/responses/{id} 將無法回傳該內容。
false請求非同步執行。支援與否取決於所選模型。建立呼叫會立即回傳,通常狀態為 queued 或 in_progress。請輪詢 Retrieve a response 直到狀態變為 completed、incomplete、failed 或 cancelled。當背景處理暫時不可用時,背景請求可能會回傳 503。
工具選擇策略,例如 auto、none、required,或指定單一工具的物件。支援的值取決於所選模型。
當所選模型支援時,可回傳額外的輸出區段。
串流選項。若所選模型支援,include_obfuscation 將會被轉發。
當所選模型支援時,針對長對話的截斷策略。
TokenLab 以標準服務層級提供 Responses 請求服務並進行計費。接受 auto 與 default。其他值(如 flex 或 priority)將會從請求中移除,並以標準價格計費。
對可重複使用提示詞模板與變數的參照。
隨回應儲存的自訂元資料。
文字輸出設定。text.format 的支援程度取決於所選模型。
當所選模型支援時,是否允許平行執行多個工具呼叫。
核取取樣參數 (0-1)。
推理選項(包含 effort),取決於所選模型。
回應 (Response)
回應的唯一識別碼。
固定為 response。
回應建立時的 Unix 時間戳記。
回應狀態:queued、in_progress、completed、incomplete、failed 或 cancelled。即使 HTTP 請求成功,也請務必檢查此欄位。
模型產生的輸出項目列表。
Token 使用統計數據。
相關端點 (Related Endpoints)
GET /v1/responses/{id}檢索已儲存的回應。DELETE /v1/responses/{id}刪除已儲存的回應。此操作不會取消生成。POST /v1/responses/compact壓縮對話並回傳response.compaction物件。wss://api.tokenlab.sh/v1/responses透過 WebSocket 建立回應。請參閱 串流 (Streaming)。- 取消、輸入項目與輸入 Token 等端點目前尚未開放。
請求
curl -X POST "https://api.tokenlab.sh/v1/responses" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-terra",
"input": [
{"type": "message", "role": "user", "content": "Hello!"}
],
"max_output_tokens": 1000
}'from openai import OpenAI
client = OpenAI(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh/v1"
)
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{"type": "message", "role": "user", "content": "Hello!"}
],
max_output_tokens=1000
)
print(response.output)import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'sk-your-api-key',
baseURL: 'https://api.tokenlab.sh/v1'
});
const response = await client.responses.create({
model: 'gpt-5.6-terra',
input: [
{ type: 'message', role: 'user', content: 'Hello!' }
],
max_output_tokens: 1000
});
console.log(response.output);package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
payload := map[string]interface{}{
"model": "gpt-5.6-terra",
"input": []map[string]interface{}{
{"type": "message", "role": "user", "content": "Hello!"},
},
"max_output_tokens": 1000,
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", "https://api.tokenlab.sh/v1/responses", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer sk-your-api-key")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["output"])
}<?php
$ch = curl_init('https://api.tokenlab.sh/v1/responses');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer sk-your-api-key'
],
CURLOPT_POSTFIELDS => json_encode([
'model' => 'gpt-5.6-terra',
'input' => [
['type' => 'message', 'role' => 'user', 'content' => 'Hello!']
],
'max_output_tokens' => 1000
])
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data['output']);視覺輸入範例 (Vision Input Example)
透過將影像放置在 message.content 中的 input_image 區塊,即可使用具備影像處理能力的模型。image_url 的值可以是公開 URL 或 Base64 資料 URL。
{
"model": "gpt-5.6-terra",
"input": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "請描述這張圖片。"
},
{
"type": "input_image",
"image_url": "https://example.com/demo.jpg"
}
]
}
]
}{
"model": "gpt-5.6-terra",
"input": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "請描述這張圖片。"
},
{
"type": "input_image",
"image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
]
}
]
}回應
{
"id": "resp_abc123",
"object": "response",
"created_at": 1706000000,
"status": "completed",
"model": "gpt-5.6-terra",
"output": [
{
"id": "msg_abc123",
"type": "message",
"status": "completed",
"role": "assistant",
"content": [
{"type": "output_text", "text": "你好!今天有什麼我可以幫你的嗎?", "annotations": []}
]
}
],
"usage": {
"input_tokens": 10,
"output_tokens": 12,
"total_tokens": 22
}
}錯誤 (Errors)
錯誤使用 OpenAI 風格的 error 物件。常見情況:400 為欄位無效或模型不支援 Responses 格式,401 為金鑰無效,402 為餘額不足,404 為未知的 previous_response_id,429 為速率限制,503 為模型目前無法處理請求。請參閱 處理 API 錯誤。
授權
BearerAuth API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
用於停止相同請求二次執行的選用鍵。每個請求請發送一個新的唯一值(例如 UUID),並在逾時重試時保留該值。使用相同鍵的重試不會再次執行:它會回傳 409 與 idempotency_replay_unavailable,若主體內容已變更則通常回傳 idempotency_conflict。例外:當非串流結果在客戶端中斷連線後完成時,在 24 小時內使用相同鍵與主體進行重試,將回傳該結果(上限 1 MB),並附帶標頭 Idempotent-Replayed: true 且不進行二次收費。超過 255 個字元的鍵將被忽略,且該請求將不具備冪等性保護。若設定 background: true,使用相同鍵與主體進行重試將回傳原始回應物件,且不會建立或收取二次費用;若主體不同則會被拒絕,且不保證其狀態碼。請參閱 安全地使用冪等鍵進行重試。
1 <= length <= 255請求主體
application/json
回應
application/json
application/json
application/json
application/json
application/json