API Timbrica

Запускайте инструменты Timbrica из своего кода или из ИИ-агента. Каждый вызов оплачивается с заранее пополненного баланса токенов, цена известна до запуска, а без выданного результата токены не списываются.

Быстрый старт

Каталог открыт без ключа: тулы и цены видны ещё до регистрации.

# 1. Что можно вызвать?
curl https://timbrica.com/v1/tools

# 2. Сколько это будет стоить?
curl -X POST https://timbrica.com/v1/tools/dns-lookup/estimate \
  -H "Authorization: Bearer $TIMBRICA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"name":"example.com"}}'

# 3. Запуск
curl -X POST https://timbrica.com/v1/tools/dns-lookup/runs \
  -H "Authorization: Bearer $TIMBRICA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"input":{"name":"example.com","type":"A"}}'

Полосы выполнения

Тул объявляет, в каких полосах (lanes) он работает. Передайте "lane" в запросе или не передавайте — тогда это auto, самая дешёвая из доступных.

Ограничения частоты зависят от полосы

Две полосы обходятся нам совсем по-разному, поэтому и ограничены по-разному. Браузерный запуск идёт на вашей машине; серверный занимает воркер в том же пуле, что отрисовывает страницы для людей, читающих сайт.

Есть и общий потолок: не больше 12 запусков серверной полосы одновременно по всем ключам. Упёршись в него, вы получите 429 concurrency_limited с "scope":"global" — это не про вас, и короткий повтор его снимает. На браузерную полосу этот потолок не действует.

Файлы

Медиатулы принимают файл, загруженный заранее. Загрузите байты или дайте адрес, и мы скачаем файл сами — удобно, когда у модели есть ссылка, но нет файла.

# загрузить байты…
curl -X POST https://timbrica.com/v1/uploads \
  -H "Authorization: Bearer $TIMBRICA_KEY" \
  -F "file=@song.mp3"

# …или дать адрес
curl -X POST https://timbrica.com/v1/uploads \
  -H "Authorization: Bearer $TIMBRICA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/song.mp3"}'

# затем сослаться на полученный id
{"input":{"audio":{"file_id":"01J…"}}}

Результат приходит ссылкой, а не в теле ответа: JSON-вызов не должен отвечать сотней мегабайт. И входы, и результаты хранятся ограниченное время — заберите результат, пока он не истёк.

MCP

Весь каталог доступен как собственные инструменты любому MCP-клиенту (Claude, Cursor и другим) одной строкой настройки — без SDK и связующего кода.

{
  "mcpServers": {
    "timbrica": {
      "url": "https://timbrica.com/mcp",
      "headers": { "Authorization": "Bearer $TIMBRICA_KEY" }
    }
  }
}

Подключение из ChatGPT или Claude

Эти два клиента не принимают вставленный ключ: удалённый MCP-сервер они подключают через OAuth. Дайте им адрес и больше ничего — остальное они найдут сами и пришлют вас сюда войти и подтвердить:

https://timbrica.com/mcp

Подтверждение — один раз, на странице, где названо приложение и баланс, который оно сможет тратить. Каждый его вызов списывается с этого баланса, подключение видно в профиле на вкладке API, и отключение там сразу останавливает приложение. Токен подключения работает только с /mcp и не годится для REST, поэтому подтвердить подключение — меньше, чем отдать ключ.

Ключ в заголовке остаётся способом для всего остального: ваших скриптов, редактора, агента на вашем сервере. Тот же каталог, тот же баланс, те же ограничения.

Баланс

Баланс — GET /v1/balance. Смотрите spendable_by_lane, а не available: часть токенов (приветственные) вызовы API не оплачивает, и общий баланс может быть верным числом не того кошелька.

Агент не может пополнить баланс сам — подтверждение оплаты требует человека. POST /v1/billing/topup_link возвращает ссылку для владельца аккаунта.

Как сообщить, что что-то не так

POST /v1/feedback — обратный канал, и он не тратит токенов: сообщение о дефекте ничего не списывает. Наша телеметрия и так записывает, что произошло: статус, ошибку, цену и время каждого запуска. Не видит она вызова, который вернул 200 с неверным ответом, схемы, расходящейся с действительностью, и тула, который вам нужен, а у нас его нет.

curl -X POST https://timbrica.com/v1/feedback \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"bug","tool":"ocr","run_id":"01J…",
       "message":"Распознанный текст пуст на чистом скане 300 dpi.",
       "expected":"текст страницы","actual":"пустой файл"}'

type — одно из bug, tool_request, docs, other. Всё, кроме type и message, необязательно.

Ограничение — 20 сообщений в час на ключ: дефицит здесь не процессор, а человек, который их читает. Повторы одного и того же сообщения схлопываются в одну запись, так что цикл повторов не завалит очередь.

Инструменты