Using the API

Using the API

Choose a protocol and model, authenticate, send a request, and parse the result.

1. Choose an Integration

For desktop and command-line clients, start with the matching Agent Quick Start guide. For your own application, choose the protocol used by your existing code:

Protocol & guide	POST path	Authentication
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
Image generation	/v1/images/generations	Authorization: Bearer …

These endpoints have different request and response schemas. Changing the URL alone does not convert a request between protocols. Gemini Interactions is also distinct from generateContent.

2. Prepare the Address, Key and Model

The API root is https://api.tokatlas.ai. Direct HTTP requests append the full path from the table. A client’s Base URL may instead require only the root or /v1; follow its guide to avoid duplicating the path.

Prepare a Tokatlas API key and choose an exact model ID enabled for your account and supported by the endpoint. Adjust sample model names and YOUR_... placeholders for your account. Keep keys in backend configuration or environment variables.

3. Complete Your First Request

List Available Models

Run these setup commands in a macOS/Linux terminal, WSL, or Git Bash. Choose a language below to query models. Replace the key placeholder first:

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

See language setup. Set API_KEY and replace model, file URL, and ID placeholders first. Each version displays the raw response to the same request.

cURL

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)

JavaScript

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());
    }
}

Success returns JSON containing data[].id. Choose an ID enabled for Chat Completions and set it as MODEL_ID below. Listing a model does not establish support for every endpoint; check its model details for capabilities.

Send Text and Read the Answer

In the same terminal, set the model ID you just found. Keep the API_BASE_URL and API_KEY variables from above:

export MODEL_ID='YOUR_ENABLED_CHAT_MODEL_ID'

Choose one method. All four examples call the same endpoint and ask the model to reply with OK.

• cURL: paste into the terminal to display the complete JSON response.
• Python: requires Python 3. Save as chat.py and run python3 chat.py. Uses only the standard library; no packages to install.
• JavaScript: requires Node.js 18 or later. Save as chat.mjs and run node chat.mjs. No packages to install; run locally or on a server.
• Java: requires JDK 11 or later. Save as Chat.java and run java Chat.java. Uses the built-in HttpClient without additional dependencies and prints the complete JSON response.

cURL

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"])

JavaScript

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 and JavaScript print OK or the model’s short reply. cURL and Java display the full JSON; read the answer at choices[0].message.content, or data.choices[0].message.content for a wrapped response. The request should also appear in Tokatlas usage. For HTTP errors, follow the troubleshooting table below.

Running the Language Examples

API pages provide cURL, Python, JavaScript, and Java request tabs. Choose one to run; existing Go examples are retained.

Tab	Requirements and command
cURL	Run in macOS/Linux, WSL, or Git Bash. Requires cURL 7.76+ for --fail-with-body.
Python	Python 3. When the example imports requests, install it with python3 -m pip install requests. Save as example.py; run python3 example.py.
JavaScript	Node.js 18+. Save as example.mjs; run node example.mjs. No additional packages.
Java	JDK 11+. Save programs declaring public class Example as Example.java; run java Example.java. Uses the built-in HttpClient.

Set API_KEY in the same terminal. Replace model IDs, file URLs, task IDs, and Base64 placeholders as instructed on each page. All languages expose the same raw response format. Full Python workflows for tool execution, image storage, and video polling are marked separately; one request does not perform those follow-up steps automatically.

Installation commands, environment setup, JSON configuration, and response examples retain their native format rather than being translated to programming languages.

4. Read Results and Continue the Conversation

Check the HTTP status before parsing the documented response. When a response has a code/data envelope, the protocol object is in data; native SDKs need a compatible direct response. Process stream: true responses as SSE events rather than calling response.json() on the whole stream.

Chat and Messages require prior messages in the next request. Responses and Interactions can continue by ID only when the route supports storage and the prior result remains accessible; otherwise, replay the history using that protocol’s format.

A tool call asks your application to execute a function and return a matching result. A queued video task must finish before you can download it.

5. Troubleshoot

Symptom	Check first
401 / 403	Key, authentication headers, account and model access
404	API root, complete request path and model ID
400	Schema, required fields and model-supported parameters
429	Rate limits; use bounded retry backoff
Text works but tools fail	Model tool support, call IDs and result format

For complete generation and download examples, see Images and Video.