Cookbook · receitas de integração

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

✓Todos os exemplos abaixo usam openrouter/openai/gpt-4o-mini como modelo. Troque por qualquer ID em /docs/models.

LangChain (Python)

python

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

llm = ChatOpenAI(
    api_key="sk-tokia-...",
    base_url="https://api.usetokia.com/v1",
    model="openrouter/openai/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("openrouter/openai/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-tokia-...",
    model="openrouter/openai/gpt-4o-mini",
    is_chat_model=True,
)
Settings.embed_model = OpenAIEmbedding(
    api_base="https://api.usetokia.com/v1",
    api_key="sk-tokia-...",
    model="openrouter/openai/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": "anthropic/claude-sonnet-4-6",
      "apiKey": "sk-tokia-...",
      "apiBase": "https://api.usetokia.com/v1"
    },
    {
      "title": "Tokia — GPT-4o mini (barato)",
      "provider": "openai",
      "model": "openrouter/openai/gpt-4o-mini",
      "apiKey": "sk-tokia-...",
      "apiBase": "https://api.usetokia.com/v1"
    }
  ]
}

Use Ctrl/Cmd + Shift + L pra 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-tokia-…
Model: qualquer ID do catálogo (ex: openrouter/openai/gpt-4o-mini)

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": "openrouter/openai/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": "openrouter/openai/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 (pra ter billing BRL + observability + fallback automático), aponte o OPENAI_API_BASE pro endpoint Tokia:

python

from litellm import completion

response = completion(
    model="openai/openrouter/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-tokia-...",
    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/openrouter/openai/gpt-4o-mini
      api_base: https://api.usetokia.com/v1
      api_key: sk-tokia-...

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

✓Por que usar LiteLLM se Tokia já é proxy? Pra fallback duplo: Tokia roteia entre múltiplos providers, e LiteLLM acima Tokia adiciona retry/timeout config + caching local. Stack robusto pra prod brasileiro.

Mistral AI direto via Tokia

Tokia já roteia GPT/Claude/DeepSeek via OpenRouter. Pra modelos Mistral via Tokia, mesmo padrão OpenAI-compatible:

python

from openai import OpenAI

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

# Mistral Large via OpenRouter
response = client.chat.completions.create(
    model="openrouter/mistralai/mistral-large",
    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)

Pra modelos Mistral hospedados na Europa (compliance GDPR/LGPD com dados no exterior controlado):

openrouter/mistralai/mistral-small-3 — barato, rápido
openrouter/mistralai/mistral-large — qualidade Claude Sonnet
openrouter/mistralai/codestral — code-tuned

✓Mistral é euro-soberano (servidores França). Pra clientes Tokia em setores regulados (jurídico, saúde, gov), pode justificar markup adicional pelo argumento data residency.

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 pra 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 pra Tokia

    # Fallback Tokia
    client = OpenAI(
        api_key="sk-tokia-...",
        base_url="https://api.usetokia.com/v1",
    )
    response = client.chat.completions.create(
        model="openrouter/meta-llama/llama-3.3-70b-instruct",
        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ó pra 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)

✓Métrica útil: cobre 60-70% das queries com Ollama local (custo zero) e joga 30% pra Tokia. Ideal pra apps de alto volume com queries variadas (chatbots, assistentes corporativos).

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 pra 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-tokia-...",
    "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 };

⚠Zapier free tier limita "Run JavaScript" a 1s de execução. Use modelos rápidos (gpt-4o-mini, gemini-flash). Pra modelos mais lentos (claude sonnet 4.6 ~3-5s), faz upgrade Zapier Starter ($20/mês).

Make.com (Integromat)

Concorrente do Zapier com melhor preço pra 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-tokia-...
  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-tokia-...
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 pra forçar custom endpoint

✓Cursor Tab Autocomplete usa modelo proprietário deles — não roteia via Tokia. Só Chat + Composer + Cmd-K usam o endpoint configurado. Pra autocomplete custom, use continue.dev (que aceita modelo qualquer pra autocomplete também).

Próximos

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