Первый запрос

01 Создайте ключ

Откройте консоль, пополните баланс и перейдите в раздел «Ключи». Кнопка «Создать ключ» просит имя — назовите ключ по сервису, который будет им пользоваться: backend-prod, bot-staging. Так ключ можно отозвать, не задев остальные интеграции.

• Секрет показывается один раз. Скопируйте его сразу — в списке остаются только префикс и дата создания.
• Ключ нельзя восстановить. Потеряли — отзовите старый и выпустите новый, это занимает секунды.
• Ключей может быть сколько угодно. Баланс и лимиты общие на аккаунт, расход виден по каждому ключу отдельно.

02 Сохраните ключ в переменную окружения

Дальше во всех примерах ключ читается из переменной TOKENDOCK_API_KEY. Это избавляет от случайного коммита секрета и позволяет менять ключ, не трогая код.

# macOS и Linux — переменная в текущей сессии
export TOKENDOCK_API_KEY="sk-td-4f9c1a2e8b7d3056a1c9e4f2b8d70a63"

# чтобы ключ пережил перезапуск терминала
echo 'export TOKENDOCK_API_KEY="sk-td-4f9c1a2e8b7d3056a1c9e4f2b8d70a63"' >> ~/.zshrc

# Windows PowerShell — переменная в текущей сессии
$env:TOKENDOCK_API_KEY = "sk-td-4f9c1a2e8b7d3056a1c9e4f2b8d70a63"

# постоянная переменная пользователя
setx TOKENDOCK_API_KEY "sk-td-4f9c1a2e8b7d3056a1c9e4f2b8d70a63"

В проекте держите ключ в .env, а сам файл — в .gitignore. В CI и на сервере используйте штатное хранилище секретов, а не переменные в конфиге сборки.

03 Отправьте первый запрос

Начнём с openai/gpt-4.1-mini — недорогая модель с контекстом 1M токенов, её хватает для проверки связки. Полный список id — в каталоге.

curl https://api.tokendock.cloud/v1/chat/completions \
  -H "Authorization: Bearer $TOKENDOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      { "role": "user", "content": "Привет. Ответь одним предложением." }
    ]
  }'

Тот же запрос через официальные SDK. Ставим библиотеку — код ниже работает и с Python, и с Node.js без единой строчки, специфичной для TokenDock.

pip install openai       # Python
npm install openai       # Node.js

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokendock.cloud/v1",
    api_key=os.environ["TOKENDOCK_API_KEY"],
)

response = client.chat.completions.create(
    model="openai/gpt-4.1-mini",
    messages=[
        {"role": "user", "content": "Привет. Ответь одним предложением."},
    ],
)

print(response.choices[0].message.content)
print(response.usage)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.tokendock.cloud/v1",
  apiKey: process.env.TOKENDOCK_API_KEY,
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4.1-mini",
  messages: [
    { role: "user", content: "Привет. Ответь одним предложением." },
  ],
});

console.log(response.choices[0].message.content);
console.log(response.usage);

Единственное отличие от кода, который ходит напрямую к OpenAI — параметр base_url (в Node.js — baseURL). Всё остальное совпадает: те же методы, те же поля, те же ошибки.

Что вернётся

Ответ приходит в формате OpenAI. Текст лежит в choices[0].message.content, причина остановки — в finish_reason, потраченные токены — в usage.

{
  "id": "chatcmpl-td-9f2c41ba7e0d",
  "object": "chat.completion",
  "created": 1787046060,
  "model": "openai/gpt-4.1-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет — на связи, спрашивайте."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 9,
    "total_tokens": 30
  }
}

• finish_reason: "stop" — модель закончила сама. "length" означает, что упёрлись в max_tokens.
• prompt_tokens — всё, что ушло в модель, включая system-сообщение и описания tools.
• completion_tokens — то, что модель сгенерировала. По этим двум числам считается стоимость запроса.

Проверить баланс и расход

Баланс виден в шапке консоли и обновляется после каждого запроса. Раздел «Расходы» показывает историю: дата, модель, ключ, число токенов и стоимость строки. Фильтр по ключу отвечает на вопрос «какой сервис съел деньги», фильтр по модели — «на чём именно».

• Списание происходит по факту ответа — по usage, а не по оценке заранее.
• Цены в каталоге указаны за 1M токенов, отдельно вход и выход.
• Когда баланс уходит в ноль, API отвечает 402, а не начинает копить долг.

Если что-то не работает

Четыре ответа, на которые приходится большая часть первых запросов.

Если ответ вообще не приходит — проверьте, что из сети открыт исходящий HTTPS на api.tokendock.cloud, и что корпоративный прокси не подменяет сертификат. Разбор сетевых ограничений — в разделе интеграции и SDK.