TokenLab

文字

建立回應 (Create Response)

使用 OpenAI Responses API 格式建立回應

POST
/v1/responses

當模型的 accepted_request_formats 包含 openai_responses 時,請使用此端點。請求與回應將使用 Responses API 格式且不會被轉換:若模型不支援該格式,此處會回傳 400,因此請改用 Chat Completions。選用欄位與支援的值取決於所選模型。

請求主體 (Request Body)

modelstring必填

所使用模型的 ID。請參閱 Models 以查看可用選項。

inputstring | array

回應的輸入內容。當請求改為使用可重複使用的 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,..." }
instructionsstring

模型的系統指令(等同於系統訊息)。

max_output_tokensinteger

生成 Token 的最大數量。

temperaturenumber

取樣溫度。支援的值與預設值取決於所選模型。

toolsarray

模型可能呼叫的工具。支援的類型與組合取決於所選模型。

streamboolean預設值: false

若為 true,則回傳事件串流。請參閱 串流 (Streaming)。

previous_response_idstring

用於接續對話的先前回應 ID。該回應必須屬於您的帳戶且仍被儲存;否則請求將回傳 404 並附帶 response_not_found 代碼。請使用產生該回應的模型進行接續。若產生該回應的服務暫時無法使用,請求可能會回傳 503。

storeboolean預設值: true

是否儲存回應以供後續檢索及作為 previous_response_id 使用。若設為 false,TokenLab 將不會保留該回應,且 GET /v1/responses/{id} 將無法回傳該內容。

backgroundboolean預設值: false

請求非同步執行。支援與否取決於所選模型。建立呼叫會立即回傳,通常狀態為 queued 或 in_progress。請輪詢 Retrieve a response 直到狀態變為 completed、incomplete、failed 或 cancelled。當背景處理暫時不可用時,背景請求可能會回傳 503。

tool_choicestring | object

工具選擇策略,例如 auto、none、required,或指定單一工具的物件。支援的值取決於所選模型。

includearray

當所選模型支援時,可回傳額外的輸出區段。

stream_optionsobject

串流選項。若所選模型支援,include_obfuscation 將會被轉發。

truncationstring

當所選模型支援時,針對長對話的截斷策略。

service_tierstring

TokenLab 以標準服務層級提供 Responses 請求服務並進行計費。接受 auto 與 default。其他值(如 flex 或 priority)將會從請求中移除,並以標準價格計費。

promptobject

對可重複使用提示詞模板與變數的參照。

metadataobject

隨回應儲存的自訂元資料。

textobject

文字輸出設定。text.format 的支援程度取決於所選模型。

parallel_tool_callsboolean

當所選模型支援時,是否允許平行執行多個工具呼叫。

top_pnumber

核取取樣參數 (0-1)。

reasoningobject

推理選項(包含 effort),取決於所選模型。

回應 (Response)

idstring

回應的唯一識別碼。

objectstring

固定為 response。

created_atinteger

回應建立時的 Unix 時間戳記。

statusstring

回應狀態:queued、in_progress、completed、incomplete、failed 或 cancelled。即使 HTTP 請求成功,也請務必檢查此欄位。

outputarray

模型產生的輸出項目列表。

usageobject

Token 使用統計數據。

請求

cURL
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
  }'
Python
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)
JavaScript
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);
Go
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
<?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..."
        }
      ]
    }
  ]
}

回應

Response
{
  "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
AuthorizationBearer <token>

API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。

位置: header

請求標頭

X-TokenLab-Delivery-Policy?string

單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。

可選值

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

用於停止相同請求二次執行的選用鍵。每個請求請發送一個新的唯一值(例如 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