回應

建立回應

相容 OpenAI 的 Responses API，支援文字生成與多輪對話。

POST /v1/responses

根據文字輸入產生模型回應，支援單輪查詢、多輪對話，以及串流或非串流輸出。

採用 OpenAI Responses API 請求格式
支援純文字與結構化訊息輸入
在路由支援儲存時，以 store 保留回應，再透過 previous_response_id 接續對話

圖像與檔案分析請參閱檔案分析；工具使用請參閱工具呼叫。

端點

text

https://api.tokatlas.ai/v1/responses

身分驗證

所有端點均需要 Bearer Token 驗證。

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

重要

請勿將真實 API 金鑰提交至程式碼儲存庫，或公開於用戶端程式碼中。

請求本文

參數	類型	必填	預設值	說明
`model`	string	是	-	產生回應的模型
`input`	string or array	是	-	傳入模型的文字
`instructions`	string	否	-	插入模型上下文的系統（或開發者）訊息
`max_output_tokens`	integer	否	-	生成 Token 上限，包含推理 Token
`stream`	boolean	否	`false`	是否透過 SSE 傳回串流回應
`store`	boolean	否	`true`	是否儲存回應以供日後取得
`temperature`	number	否	`1.0`	取樣溫度，範圍 0–2
`top_p`	number	否	`1.0`	核心取樣參數，範圍 0–1
`text`	object	否	-	文字回應設定（格式、詳細程度）
`reasoning`	object	否	-	推理設定（gpt-5 與 o 系列模型）
`previous_response_id`	string	否	-	多輪對話中前一個回應的 ID
`metadata`	object	否	-	回應附加的鍵值對，最多 16 組

model

以下為截至 2026-10-03 核對的官方現行型號。先依API 使用入門查詢帳戶可用模型，再將完整 ID 填入 model；官方已發布不代表您的 Tokatlas 帳戶已開通。

gpt-6.1-sol — GPT-6.1 Sol
gpt-6-astra — GPT-6 Astra
gpt-6-luna — GPT-6 Luna

官方模型文件

GPT-6.1 Sol 與 GPT-6 Astra 的工具呼叫請使用 Responses；不要將 Chat 的工具請求直接套用。

input

傳入模型的文字，可以是純字串（等同使用者訊息）或訊息項目陣列。

純文字輸入：

json

"What is the weather like in Boston today?"

包含文字內容區塊的訊息：

json

[
  {
    "role": "user",
    "content": [
      {"type": "input_text", "text": "Hello, please introduce yourself"}
    ]
  }
]

多輪對話：

json

[
  {"role": "user", "content": [{"type": "input_text", "text": "Hello"}]},
  {"role": "assistant", "content": [{"type": "output_text", "text": "Hi! How can I help you?"}]},
  {"role": "user", "content": [{"type": "input_text", "text": "Tell me about AI"}]}
]

每則訊息的 role 支援 user、assistant、system 或 developer。developer 或 system 指令的優先順序高於 user 指令。

instructions

插入模型上下文的系統（或開發者）訊息。搭配 previous_response_id 使用時，不會沿用前一個回應的指令。

json

{
  "instructions": "You are a professional Python programming tutor"
}

max_output_tokens

回應可產生的 Token 數量上限，包含可見輸出與推理 Token。最小值為 16。

stream

是否使用伺服器傳送事件（SSE）逐步傳回串流回應。

true：串流回應
false：一次傳回完整回應（預設）

store

是否儲存模型回應，以便日後透過 API 取得。無狀態請求請設為 false。

temperature

取樣溫度，範圍為 0–2。較高值（如 0.8）增加隨機性，較低值（如 0.2）讓輸出更集中。建議只調整 temperature 或 top_p 其中一項。

top_p

核心取樣參數，範圍為 0–1，用於控制生成文字的多樣性。

text

文字回應設定，預設為純文字。

json

{
  "text": {
    "format": {"type": "text"},
    "verbosity": "medium"
  }
}

可選的 verbosity：low、medium（預設）或 high。

reasoning

推理模型設定（僅適用於 gpt-5 和 o 系列）。

欄位	類型	說明
`effort`	string	推理程度：`none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`
`summary`	string	推理摘要：`auto`、`concise` 或 `detailed`

json

{
  "reasoning": {
    "effort": "high"
  }
}

previous_response_id

前一個回應的唯一 ID。使用此欄位可建立多輪對話，無須重新傳送完整歷史紀錄。

json

{
  "model": "gpt-5",
  "previous_response_id": "resp_abc123",
  "input": "Can you give me a practical example?"
}

metadata

最多 16 組鍵值對，用於儲存回應的額外資訊。鍵最長 64 個字元，值最長 512 個字元。

回應

下表描述協定回應物件。本文非串流範例若有 { "code": 200, "data": { ... } } 外層封裝，請先讀取 data；直接回傳協定物件的路由則讀取根物件。串流請按事件解析，不能將整段 SSE 當成單一 JSON。使用原生 SDK 前，須確認路由回傳 SDK 所需的直接協定格式。

欄位	類型	說明
`id`	string	回應唯一識別碼
`object`	string	物件類型，固定為 `response`
`created_at`	integer	建立時間戳記
`status`	string	回應狀態：`completed`、`failed`、`in_progress`、`cancelled`、`queued`、`incomplete`
`model`	string	回應使用的模型
`output`	array	模型產生的輸出項目陣列
`usage`	object	Token 用量統計
`error`	object or null	回應失敗時的錯誤詳情

output[]

文字對話的主要輸出類型為 message：

json

{
  "type": "message",
  "id": "msg_...",
  "status": "completed",
  "role": "assistant",
  "content": [
    {
      "type": "output_text",
      "text": "Hello! How can I help you?",
      "annotations": []
    }
  ]
}

status

值	說明
`completed`	回應已成功完成
`failed`	回應發生錯誤而失敗
`in_progress`	回應仍在生成中
`cancelled`	回應已取消
`queued`	回應正在排隊
`incomplete`	回應未完成即結束（如達到 `max_output_tokens`）

usage

欄位	類型	說明
`input_tokens`	integer	輸入 Token 數量
`output_tokens`	integer	輸出 Token 數量
`total_tokens`	integer	Token 總用量
`input_tokens_details`	object	包含 `cached_tokens` 的詳細資料
`output_tokens_details`	object	包含 `reasoning_tokens` 的詳細資料

使用範例

基本文字生成

json

{
  "model": "gpt-5",
  "input": "Hello, please introduce yourself"
}

系統指令

json

{
  "model": "gpt-5",
  "instructions": "You are a professional Python programming tutor",
  "input": "How should I learn programming?"
}

多輪對話

json

{
  "model": "gpt-5",
  "previous_response_id": "resp_abc123",
  "input": "Can you give me a practical example?"
}

非串流輸出

json

{
  "model": "gpt-5",
  "input": "Write a short essay about artificial intelligence",
  "stream": false
}

串流輸出

json

{
  "model": "gpt-5",
  "input": "Write a short essay about artificial intelligence",
  "stream": true
}

推理模型

json

{
  "model": "o3-mini",
  "input": "How much wood would a woodchuck chuck?",
  "reasoning": {
    "effort": "high"
  }
}

請求範例

執行方式見多語言範例說明。先設定 API_KEY，並替換模型、檔案網址及 ID 占位值；四種方式會顯示相同請求的原始回應。

bash

curl --fail-with-body --silent --show-error --max-time 180 \
  --request POST \
  --url "https://api.tokatlas.ai/v1/responses" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "gpt-5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Tell me about the history of artificial intelligence."
        }
      ]
    }
  ]
}'

python

import os
import requests

headers = {
    'Authorization': 'Bearer ' + os.environ["API_KEY"],
    'Content-Type': 'application/json',
}
payload = {'model': 'gpt-5',
 'input': [{'role': 'user',
            'content': [{'type': 'input_text',
                         'text': 'Tell me about the history of artificial '
                                 'intelligence.'}]}]}
response = requests.request(
    'POST', 'https://api.tokatlas.ai/v1/responses', headers=headers,
    json=payload,
    timeout=180,
)
response.raise_for_status()
print(response.text)

if (!process.env.API_KEY) throw new Error("Set API_KEY first.");
const response = await fetch("https://api.tokatlas.ai/v1/responses", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Tell me about the history of artificial intelligence."
        }
      ]
    }
  ]
}),
  signal: AbortSignal.timeout(180_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.text());

java

import java.net.URI;
import java.net.http.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("API_KEY");
        if (apiKey == null || apiKey.isBlank()) {
            throw new IllegalArgumentException("Set API_KEY first.");
        }
        String payload = String.join("\n",
            "{",
            "  \"model\": \"gpt-5\",",
            "  \"input\": [",
            "    {",
            "      \"role\": \"user\",",
            "      \"content\": [",
            "        {",
            "          \"type\": \"input_text\",",
            "          \"text\": \"Tell me about the history of artificial intelligence.\"",
            "        }",
            "      ]",
            "    }",
            "  ]",
            "}"
        );
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(30)).build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.tokatlas.ai/v1/responses"))
            .timeout(Duration.ofSeconds(180))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> response = client.send(
            request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": "
                + response.body());
        }
        System.out.println(response.body());
    }
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    url := "https://api.tokatlas.ai/v1/responses"

    payload := map[string]interface{}{
        "model": "gpt-5",
        "input": []map[string]interface{}{
            {
                "role": "user",
                "content": []map[string]string{
                    {
                        "type": "input_text",
                        "text": "Tell me about the history of artificial intelligence.",
                    },
                },
            },
        },
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+os.Getenv("API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

回應範例

非串流 (`stream: false`)

json

{
  "code": 200,
  "data": {
    "id": "resp_686eef60237881a2bd1180bb8b13de430e34c516d176ff86",
    "object": "response",
    "created_at": 1752100704,
    "status": "completed",
    "completed_at": 1752100705,
    "model": "gpt-5",
    "output": [
      {
        "id": "msg_686eef60d3e081a29283bdcbc4322fd90e34c516d176ff86",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "The history of artificial intelligence (AI) dates back to the 1950s...",
            "annotations": []
          }
        ]
      }
    ],
    "usage": {
      "input_tokens": 28,
      "output_tokens": 320,
      "total_tokens": 348,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens_details": {
        "reasoning_tokens": 0
      }
    },
    "temperature": 1.0,
    "top_p": 1.0,
    "store": true,
    "metadata": {}
  }
}

串流 (`stream: true`)

當 stream 為 true，API 會傳回 Content-Type: text/event-stream 的 SSE 串流。每個事件都是描述回應增量的 JSON 物件。串接 response.output_text.delta 事件即可取得完整文字。

text

event: response.created
data: {"type":"response.created","response":{"id":"resp_...","object":"response","status":"in_progress",...}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","id":"msg_...","status":"in_progress","role":"assistant","content":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_...","output_index":0,"content_index":0,"delta":"The"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_...","output_index":0,"content_index":0,"delta":" history"}

event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_...","output_index":0,"content_index":0,"text":"The history of artificial intelligence (AI) dates back to the 1950s..."}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_...","status":"completed",...}}

建立回應 ​

端點 ​

身分驗證 ​

請求本文 ​

model ​

input ​

instructions ​

max_output_tokens ​

stream ​

store ​

temperature ​

top_p ​

text ​

reasoning ​

previous_response_id ​

metadata ​

回應 ​

output[] ​

status ​

usage ​

使用範例 ​

基本文字生成 ​

系統指令 ​

多輪對話 ​

非串流輸出 ​

串流輸出 ​

推理模型 ​

請求範例 ​

回應範例 ​

非串流 (stream: false) ​

串流 (stream: true) ​

相關主題 ​

建立回應

端點

身分驗證

請求本文

model

input

instructions

max_output_tokens

stream

store

temperature

top_p

text

reasoning

previous_response_id

metadata

回應

output[]

status

usage

使用範例

基本文字生成

系統指令

多輪對話

非串流輸出

串流輸出

推理模型

請求範例

回應範例

非串流 (`stream: false`)

串流 (`stream: true`)

相關主題