Tokiadocs
⌘K

SDKs · qualquer cliente OpenAI-compatible

Tokia é 100% OpenAI-compatible — qualquer SDK que aceite base_url customizado funciona sem refactor. Mostro exemplos minimum-viable nas 7 linguagens mais usadas.

✓Você pode usar qualquer SDK OpenAI-compatible sem precisar instalar nada da Tokia. Os SDKs oficiais OpenAI (Python, Node, Java, Go, .NET) ou Anthropic (Python, Node) já roteiam pra Tokia com 2 linhas de mudança.

SDK oficial Tokia (opcional, recomendado pra Node)

Pra quem quer ergonomia BR (auto-retry com backoff, helper de saldo, tipos pt-BR), publicamos o pacote oficial @tokia/sdk v0.3 no npm.

bash
npm install @tokia/sdk
# ou
pnpm add @tokia/sdk
ts
import { TokiaClient } from "@tokia/sdk";

const tokia = new TokiaClient({ apiKey: "sk-tokia-..." });

// Chat completion (mesmo signature do SDK OpenAI)
const r = await tokia.chat.completions.create({
  model: "claude-sonnet-46",
  messages: [{ role: "user", content: "Olá!" }],
});

// Helpers Tokia (não existe no SDK OpenAI):
const balance = await tokia.balance.get();         // R$ saldo atual
const models = await tokia.models.list("chat");   // filtra por categoria
const usage = await tokia.usage.summary({ days: 30 }); // resumo

Inclui auto-retry exponencial (Sprint 114) que respeita o header retry-after da Tokia (Sprint 177). Sem código extra do seu lado.

CLI oficial Tokia (terminal)

Pra usar Tokia direto do terminal sem escrever código, tem o @tokia/cli v0.3:

bash
npm install -g @tokia/cli
tokia login                          # configura sk-tokia-...
tokia balance                        # saldo atual
tokia chat "Resume em 1 frase: ..."  # chat rápido
tokia models --category chat         # lista modelos chat (Sprint 181)
tokia keys list                      # lista API keys
tokia usage --days 30                # resumo de uso 30d (Sprint 188)

Python (SDK OpenAI oficial)

bash
pip install openai
python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.usetokia.com/v1",
    api_key="sk-tokia-...",
)

response = client.chat.completions.create(
    model="claude-sonnet-46",
    messages=[{"role": "user", "content": "Olá!"}],
)
print(response.choices[0].message.content)

Streaming

python
stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Conte uma história curta"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Node.js / TypeScript (SDK OpenAI oficial)

bash
npm install openai
typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.usetokia.com/v1",
  apiKey: process.env.TOKIA_API_KEY,
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-46",
  messages: [{ role: "user", content: "Olá!" }],
});
console.log(response.choices[0]?.message.content);

Go (sashabaranov/go-openai)

bash
go get github.com/sashabaranov/go-openai
go
package main

import (
    "context"
    "fmt"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("sk-tokia-...")
    config.BaseURL = "https://api.usetokia.com/v1"
    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "gpt-4o-mini",
            Messages: []openai.ChatCompletionMessage{
                {Role: openai.ChatMessageRoleUser, Content: "Olá!"},
            },
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.Choices[0].Message.Content)
}

Rust (async-openai)

toml
# Cargo.toml
[dependencies]
async-openai = "0.27"
tokio = { version = "1", features = ["full"] }
rust
use async_openai::{
    config::OpenAIConfig,
    types::{ChatCompletionRequestUserMessageArgs, CreateChatCompletionRequestArgs},
    Client,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = OpenAIConfig::new()
        .with_api_base("https://api.usetokia.com/v1")
        .with_api_key("sk-tokia-...");
    let client = Client::with_config(config);

    let request = CreateChatCompletionRequestArgs::default()
        .model("claude-sonnet-46")
        .messages([
            ChatCompletionRequestUserMessageArgs::default()
                .content("Olá!")
                .build()?
                .into(),
        ])
        .build()?;

    let response = client.chat().create(request).await?;
    println!("{}", response.choices[0].message.content.as_deref().unwrap_or(""));
    Ok(())
}

PHP (openai-php/client)

bash
composer require openai-php/client
php
<?php
require_once __DIR__ . "/vendor/autoload.php";

$client = OpenAI::factory()
    ->withBaseUri("https://api.usetokia.com/v1")
    ->withApiKey("sk-tokia-...")
    ->make();

$response = $client->chat()->create([
    "model" => "gpt-4o-mini",
    "messages" => [
        ["role" => "user", "content" => "Olá!"],
    ],
]);

echo $response->choices[0]->message->content;

Ruby (alexrudall/ruby-openai)

bash
gem install ruby-openai
ruby
require "openai"

client = OpenAI::Client.new(
  access_token: "sk-tokia-...",
  uri_base: "https://api.usetokia.com/v1",
)

response = client.chat(
  parameters: {
    model: "claude-sonnet-46",
    messages: [{ role: "user", content: "Olá!" }],
  },
)

puts response.dig("choices", 0, "message", "content")

cURL (qualquer linguagem)

bash
curl https://api.usetokia.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tokia-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Olá!"}]
  }'

Anthropic SDK (Python/Node) — funciona também?

O SDK oficial da Anthropic (@anthropic-ai/sdk) é incompatível com endpoints OpenAI-style. Use o SDK da OpenAI mesmo quando o modelo for Claude — Tokia traduz internamente.

⚠Pra usar Claude via SDK Anthropic direto (sem Tokia), você precisaria conta Anthropic + cartão internacional. Tokia evita isso.

Variáveis de ambiente recomendadas

bash
# .env
TOKIA_API_KEY=sk-tokia-Igbws93hgs-7H8cuQDoGJA
TOKIA_BASE_URL=https://api.usetokia.com/v1

# uso no código (Python)
# client = OpenAI(base_url=os.environ["TOKIA_BASE_URL"], api_key=os.environ["TOKIA_API_KEY"])
✓Adiciona .env ao .gitignore. Pra dev local, use dotenv (Python) ou --env-file (Node 20+). Pra prod, sete env vars na plataforma (Vercel/Coolify/Heroku/etc).

Próximos passos

  • Cookbook — receitas pra LangChain, Vercel AI SDK, LlamaIndex, continue.dev, Zapier, Make, Cursor, n8n e Ollama bridge
  • Referência API — parâmetros completos /v1/chat/completions
  • Troubleshooting — erros comuns + fixes
  • Calculadora — estime custo BRL/mês comparado a OpenAI direto