Cookbook · receitas de integração

Snippets prontos para os frameworks/ferramentas mais usados. Tokia é OpenAI-compatible, então qualquer SDK que aceite custom base_url funciona, basta trocar 2 linhas.

LangChain (Python)

python

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage

llm = ChatOpenAI(
    api_key="sk-...",
    base_url="https://api.usetokia.com/v1",
    model="gpt-4o-mini",
    temperature=0.3,
)

response = llm.invoke([
    SystemMessage(content="Responda em pt-BR, 1 frase."),
    HumanMessage(content="Qual a capital da França?"),
])
print(response.content)  # "Paris é a capital da França."

LangChain streaming

python

for chunk in llm.stream("Liste 5 frutas tropicais"):
    print(chunk.content, end="", flush=True)

Vercel AI SDK (Next.js)

typescript

// app/api/chat/route.ts
import { createOpenAI } from "@ai-sdk/openai";
import { streamText } from "ai";

const tokia = createOpenAI({
  apiKey: process.env.TOKIA_KEY,
  baseURL: "https://api.usetokia.com/v1",
});

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: tokia("gpt-4o-mini"),
    messages,
  });
  return result.toDataStreamResponse();
}

useChat hook (cliente)

typescript

"use client";
import { useChat } from "ai/react";

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({ api: "/api/chat" });
  return (
    <form onSubmit={handleSubmit}>
      {messages.map((m) => <div key={m.id}>{m.role}: {m.content}</div>)}
      <input value={input} onChange={handleInputChange} />
    </form>
  );
}

LlamaIndex (RAG)

python

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.openai_like import OpenAILike
from llama_index.embeddings.openai import OpenAIEmbedding

Settings.llm = OpenAILike(
    api_base="https://api.usetokia.com/v1",
    api_key="sk-...",
    model="gpt-4o-mini",
    is_chat_model=True,
)
Settings.embed_model = OpenAIEmbedding(
    api_base="https://api.usetokia.com/v1",
    api_key="sk-...",
    model="text-embedding-3-small",
)

# Index local docs
docs = SimpleDirectoryReader("./meus-docs").load_data()
index = VectorStoreIndex.from_documents(docs)

# Pergunta com RAG
response = index.as_query_engine().query("O que diz sobre LGPD?")
print(response)

continue.dev (VS Code)

Adicione ao ~/.continue/config.json:

json

{
  "models": [
    {
      "title": "Tokia, Claude Sonnet 4.6",
      "provider": "openai",
      "model": "claude-sonnet-46",
      "apiKey": "sk-...",
      "apiBase": "https://api.usetokia.com/v1"
    },
    {
      "title": "Tokia, GPT-4o mini (barato)",
      "provider": "openai",
      "model": "gpt-4o-mini",
      "apiKey": "sk-...",
      "apiBase": "https://api.usetokia.com/v1"
    }
  ]
}

Use Ctrl/Cmd + Shift + L para selecionar código e perguntar; troque de modelo no dropdown da sidebar. Cobrado em BRL no seu saldo Tokia.

n8n (no-code workflows)

Em qualquer node "OpenAI" do n8n:

Credentials: tipo OpenAI API → marque Override base URL
Base URL: https://api.usetokia.com/v1
API Key: sk-…
Model: qualquer ID do catálogo (ex: gpt-4o-mini)

Os dois erros que mais aparecem no n8n:

"The resource you are requesting could not be found": a Base URL está sem o /v1 no fim. Tem que ser exatamente https://api.usetokia.com/v1. O n8n completa o resto do caminho sozinho. Esse mesmo erro aparece se o node tentar /v1/completions ou /v1/responses, que não existem aqui: o formato suportado é /v1/chat/completions.
Erro de autenticação com a key certa: confira se você colou a key inteira. A key completa só aparece uma vez, na hora em que você cria. O que fica visível depois em /dashboard/keys é só o começo dela, terminando em reticências, e esse pedaço nunca autentica. Se você não guardou a key, crie outra: é de graça e não mexe no seu saldo.

cURL puro (debug)

bash

# Chat completion mais simples
curl https://api.usetokia.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Diga oi"}]
  }'

# Streaming
curl https://api.usetokia.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini","messages":[{"role":"user","content":"contar"}],"stream":true}'

LiteLLM Proxy SDK (Python)

Se você já usa LiteLLM em produção e quer roteá-lo via Tokia (para ter billing BRL + observability + fallback automático), aponte o OPENAI_API_BASE para o endpoint Tokia:

python

from litellm import completion

response = completion(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "explique inflação BR em 1 frase"}],
    api_base="https://api.usetokia.com/v1",
    api_key="sk-...",
    custom_llm_provider="openai",  # força adapter OpenAI-compatible
)
print(response.choices[0].message.content)

Modo proxy server (LiteLLM proxy → Tokia):

yaml

# litellm-config.yaml
model_list:
  - model_name: tokia-gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_base: https://api.usetokia.com/v1
      api_key: sk-...

router_settings:
  fallbacks:
    - tokia-gpt-4o-mini:
      - openai/gpt-4o-mini  # se Tokia cair (improvável), fallback direto OpenAI

Escolher modelo por força vs custo

Uma key, vários modelos. Troque só o campo model para equilibrar qualidade e custo, sempre no mesmo padrão OpenAI-compatible:

python

from openai import OpenAI

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

# Modelo forte para tarefa que exige raciocínio
response = client.chat.completions.create(
    model="claude-sonnet-46",
    messages=[
        {"role": "system", "content": "Você é especialista em direito tributário BR."},
        {"role": "user", "content": "ICMS pode incidir sobre frete?"},
    ],
)
print(response.choices[0].message.content)

Guia rápido de quando usar cada um:

gpt-4o-mini, barato e rápido para o grosso das tarefas
claude-sonnet-46, qualidade máxima para raciocínio e texto longo
deepseek-v3, ótimo custo-benefício para código

Ollama local → Tokia bridge

Se você roda Ollama local (Llama/Qwen/Phi gratuito no seu hardware) mas quer fallback Tokia quando o modelo local não consegue responder ou a máquina está sobrecarregada:

python

import requests
from openai import OpenAI

def chat_with_fallback(messages: list, prefer_local: bool = True):
    """Tenta Ollama local primeiro; se falhar/timeout, cai para Tokia."""
    if prefer_local:
        try:
            r = requests.post(
                "http://localhost:11434/v1/chat/completions",
                json={"model": "llama3:8b", "messages": messages},
                timeout=10,
            )
            if r.ok:
                return r.json()["choices"][0]["message"]["content"]
        except (requests.Timeout, requests.ConnectionError):
            pass  # local falhou → cai para Tokia

    # Fallback Tokia
    client = OpenAI(
        api_key="sk-...",
        base_url="https://api.usetokia.com/v1",
    )
    response = client.chat.completions.create(
        model="llama-3-3-70b",
        messages=messages,
    )
    return response.choices[0].message.content

Hybrid local/cloud pattern: economiza créditos Tokia em queries triviais (resolvidos por modelo 8B local) e usa qualidade superior 70B cloud só para queries difíceis. Detecção automática:

python

# Roteia por complexidade da query
def smart_route(query: str, messages: list):
    is_complex = (
        len(query) > 500  # query longa
        or "raciocínio" in query.lower()
        or "analise" in query.lower()
        or any(c.isdigit() for c in query)  # tem números (cálculo?)
    )
    return chat_with_fallback(messages, prefer_local=not is_complex)

Zapier (Code by Zapier)

Zapier não tem node nativo "Tokia" mas o action "Code by Zapier" (Run JavaScript ou Run Python) faz chamada HTTP custom. Útil para automatizar "quando nova linha em Sheets, gerar resumo IA, append na coluna B".

Run JavaScript

javascript

// Input: inputData.texto (string)
const response = await fetch("https://api.usetokia.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-4o-mini",
    messages: [
      { role: "system", content: "Resuma em 1 frase, máximo 50 palavras." },
      { role: "user", content: inputData.texto },
    ],
    max_tokens: 100,
  }),
});
const data = await response.json();
output = { resumo: data.choices[0].message.content };

Make.com (Integromat)

Concorrente do Zapier com melhor preço para alto volume. Tem módulo HTTP nativo:

text

Módulo "HTTP > Make a request":

URL:          https://api.usetokia.com/v1/chat/completions
Method:       POST
Headers:
  Authorization: Bearer sk-...
  Content-Type:  application/json
Body type:    Raw (JSON)
Body:
  {
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "{{1.text_input}}"}
    ]
  }
Parse response: Yes (JSON)

Output: 1.choices[0].message.content

Cursor IDE (alternativa continue.dev)

Cursor (cursor.sh) aceita custom API endpoint OpenAI-compatible nas configurações:

Settings → Models → "Override OpenAI Base URL" → https://api.usetokia.com/v1
API Key → sua sk-...
Models field: gpt-4o-mini,claude-sonnet-46,gemini-flash (separados por vírgula, Cursor tenta cada um)
Disable "Use OpenAI's API key" toggle para forçar custom endpoint

Próximos

Troubleshooting , debug de erros comuns
Pricing calculator , estime custo BRL/mês
Referência API , todos os parâmetros suportados