使用 API

使用 API

先選擇協定與模型，再完成驗證、發送請求及解析回應。

1. 選擇接入方式

若使用桌面程式或命令列工具，請先依側欄的 Agent 快速接入指南設定。自行開發應用程式時，按現有程式採用的協定選擇端點：

協定與文件	POST 路徑	驗證標頭
Messages	`/v1/messages`	`x-api-key` `anthropic-version`
Chat Completions	`/v1/chat/completions`	`Authorization: Bearer …`
Responses	`/v1/responses`	`Authorization: Bearer …`
Gemini generateContent	`/v1beta/models/{model}:generateContent`	`x-goog-api-key`
圖像生成	`/v1/images/generations`	`Authorization: Bearer …`

這些端點的欄位及回應結構不同，不能只替換 URL 就沿用另一種協定的請求。Gemini Interactions 也不等同於 generateContent。

2. 準備位址、金鑰與模型

API 根位址為 https://api.tokatlas.ai。直接 HTTP 請求須加上表格中的完整路徑；客戶端的 Base URL 可能只需要根位址或 /v1，請遵循該客戶端指南，避免重複路徑。

準備 Tokatlas API Key，並從帳戶的模型列表選擇已開通、支援所選端點的完整模型 ID。範例模型名稱與 YOUR_... 佔位值均需依帳戶調整。金鑰應保存在後端或環境變數中。

3. 完成第一個請求

查詢可用模型

在 macOS／Linux 終端機、Windows WSL 或 Git Bash 中執行以下設定命令。查詢模型列表可選擇下方任一語言；先把金鑰占位值換成您的金鑰：

bash

export API_BASE_URL='https://api.tokatlas.ai'
export API_KEY='YOUR_TOKATLAS_API_KEY'

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

cURLPythonJavaScriptJava

bash

curl --fail-with-body --silent --show-error --max-time 180 \
  --request GET \
  --url "https://api.tokatlas.ai/v1/models" \
  --header "Authorization: Bearer $API_KEY"

python

import os
import requests

headers = {
    'Authorization': 'Bearer ' + os.environ["API_KEY"],
}
response = requests.request(
    'GET', 'https://api.tokatlas.ai/v1/models', headers=headers,
    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/models", {
  method: "GET",
  headers: {
    "Authorization": "Bearer " + process.env.API_KEY,
  },
  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.");
        }
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(30)).build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.tokatlas.ai/v1/models"))
            .timeout(Duration.ofSeconds(180))
            .header("Authorization", "Bearer " + apiKey)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .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());
    }
}

成功時會收到包含 data[].id 的 JSON。選擇其中已開通 Chat Completions 的模型，將完整 ID 填入下方 MODEL_ID。模型列表本身不代表所有模型都支援所有端點；端點與能力請對照模型詳情。

發送文字並讀取答案

在同一個終端機中設定剛查到的模型 ID，沿用上方的 API_BASE_URL 與 API_KEY：

bash

export MODEL_ID='YOUR_ENABLED_CHAT_MODEL_ID'

選擇其中一種方式即可，四個範例都呼叫相同端點並傳送「只回覆 OK」。

cURL：直接貼到終端機執行，會顯示完整 JSON 回應。
Python：需要 Python 3，存為 chat.py，執行 python3 chat.py。只使用標準函式庫，不需安裝套件。
JavaScript：需要 Node.js 18 或更新版本，存為 chat.mjs，執行 node chat.mjs。不需安裝套件，請在本機或伺服器執行。
Java：需要 JDK 11 或更新版本，存為 Chat.java，執行 java Chat.java。使用內建 HttpClient，不需額外依賴，會顯示完整 JSON 回應。

cURLPythonJavaScriptJava

bash

curl --fail-with-body --silent --show-error \
  --max-time 120 \
  "$API_BASE_URL/v1/chat/completions" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data "{
    \"model\": \"$MODEL_ID\",
    \"messages\": [{\"role\": \"user\", \"content\": \"Reply with OK only.\"}],
    \"stream\": false
  }"

python

import json
import os
import urllib.error
import urllib.request

payload = {
    "model": os.environ["MODEL_ID"],
    "messages": [{"role": "user", "content": "Reply with OK only."}],
    "stream": False,
}
request = urllib.request.Request(
    os.environ["API_BASE_URL"].rstrip("/") + "/v1/chat/completions",
    data=json.dumps(payload).encode(),
    headers={"Authorization": "Bearer " + os.environ["API_KEY"],
             "Content-Type": "application/json"},
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        body = json.load(response)
except urllib.error.HTTPError as error:
    raise SystemExit(f"HTTP {error.code}: {error.read().decode()}")
result = body.get("data", body)
if not isinstance(result, dict) or not result.get("choices"):
    raise SystemExit("Unexpected response: " + json.dumps(body, ensure_ascii=False))
print(result["choices"][0]["message"]["content"])

const { API_BASE_URL, API_KEY, MODEL_ID } = process.env;
if (!API_BASE_URL || !API_KEY || !MODEL_ID) {
  throw new Error("Set API_BASE_URL, API_KEY, and MODEL_ID first.");
}

const response = await fetch(
  `${API_BASE_URL.replace(/\/$/, "")}/v1/chat/completions`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: MODEL_ID,
      messages: [{ role: "user", content: "Reply with OK only." }],
      stream: false,
    }),
    signal: AbortSignal.timeout(120_000),
  },
);
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
const body = await response.json();
const result = body.data ?? body;
const answer = result.choices?.[0]?.message?.content;
if (typeof answer !== "string") {
  throw new Error(`Unexpected response: ${JSON.stringify(body)}`);
}
console.log(answer);

java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Chat {
    public static void main(String[] args) throws Exception {
        String baseUrl = requiredEnv("API_BASE_URL").replaceAll("/+$", "");
        String apiKey = requiredEnv("API_KEY");
        String model = requiredEnv("MODEL_ID");
        String payload = "{\"model\":" + jsonString(model)
            + ",\"messages\":[{\"role\":\"user\","
            + "\"content\":\"Reply with OK only.\"}],\"stream\":false}";

        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(30))
            .build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/v1/chat/completions"))
            .timeout(Duration.ofSeconds(120))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .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());
    }

    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("Set " + name + " first.");
        }
        return value;
    }

    private static String jsonString(String value) {
        StringBuilder escaped = new StringBuilder("\"");
        for (char c : value.toCharArray()) {
            if (c == '"' || c == '\\') {
                escaped.append('\\').append(c);
            } else if (c < 0x20) {
                escaped.append(String.format("\\u%04x", (int) c));
            } else {
                escaped.append(c);
            }
        }
        return escaped.append('"').toString();
    }
}

Python 與 JavaScript 會直接印出 OK 或模型的簡短回覆。cURL 與 Java 會顯示完整 JSON，答案位於 choices[0].message.content；若回應有 data 封裝，則位於 data.choices[0].message.content。同時可在 Tokatlas 用量記錄查到本次請求。若出現 HTTP 錯誤，依下方排錯表修正後重試。

多語言範例執行方式

所有 API 文件均提供 cURL、Python、JavaScript 與 Java 請求標籤。選擇一種執行即可；原有 Go 範例仍保留。

標籤	環境與執行方式
cURL	在 macOS／Linux、WSL 或 Git Bash 中執行。支援 `--fail-with-body` 的 cURL 7.76+。
Python	Python 3。範例有 `import requests` 時先執行 `python3 -m pip install requests`；存為 `example.py`，執行 `python3 example.py`。
JavaScript	Node.js 18+。存為 `example.mjs`，執行 `node example.mjs`，不需額外套件。
Java	JDK 11+。`public class Example` 的程式存為 `Example.java`，執行 `java Example.java`，使用內建 HttpClient。

先在同一終端機設定 API_KEY。依各頁要求替換模型 ID、檔案網址、任務 ID 與 Base64 占位值。各種語言的原始回應格式相同；工具執行、圖片保存與影片輪詢等完整 Python 流程另外標示，不會因為發送一次請求而自動完成。

命令安裝、環境變數、JSON 設定及回應範例維持原本格式，無須切換成其他程式語言。

4. 解析結果與接續對話

先檢查 HTTP 狀態，再依各頁的回應範例解析。若回應有 code 與 data 封裝，協定物件位於 data；原生 SDK 需要與其相容的直接回包。stream: true 的回應須以 SSE 事件逐段處理，不能直接呼叫 response.json()。

Chat 與 Messages 的下一輪請求須帶入歷史訊息。Responses 與 Interactions 只有在路由支援儲存且先前結果仍可存取時，才能以先前的 ID 接續對話；否則須依各自格式回傳完整歷史。

工具呼叫表示模型提出執行要求，應用程式仍須執行函式並回傳對應結果。影片任務必須完成後才能下載。

5. 排查錯誤

現象	優先檢查
`401`／`403`	金鑰、驗證標頭、帳戶與模型權限
`404`	根位址、完整請求路徑與模型 ID
`400`	請求格式、必要欄位及模型支援的參數
`429`	速率限制，採用有上限的退避重試
有文字但工具失敗	模型的工具能力、呼叫 ID 與結果格式

完整生成與下載範例請見圖像生成與影片生成。

使用 API ​

1. 選擇接入方式 ​

2. 準備位址、金鑰與模型 ​

3. 完成第一個請求 ​

查詢可用模型 ​

發送文字並讀取答案 ​

多語言範例執行方式 ​

4. 解析結果與接續對話 ​

5. 排查錯誤 ​

1. 選擇接入方式

2. 準備位址、金鑰與模型

3. 完成第一個請求

查詢可用模型

發送文字並讀取答案

多語言範例執行方式

4. 解析結果與接續對話

5. 排查錯誤