Saltar para o conteúdo principal
Esta página documenta o skill compartilhado mantido tokenlab-api-integration. A distribuição canônica fica em hedging8563/tokenlab-skills, onde o repositório público mantém intencionalmente apenas este skill.
Use esta página para instalação do skill e orientação de workflow do agent. Para configuração por endpoint, use a página dedicada de SDK, cliente ou referência da API.

​
O que o skill faz

  • Gera exemplos mínimos executáveis para chat, imagem, áudio, vídeo, tradução e outras famílias de API da TokenLab.
  • Usa https://api.tokenlab.sh/v1 para clientes compatíveis com OpenAI e explica quando mudar para rotas nativas Anthropic ou Gemini.
  • Descobre modelos com /v1/models, /llms.txt e listas recommended_for, em vez de adivinhar a partir de listas antigas.
  • Lê o detalhes do modelo de um modelo antes de tentar novamente solicitações não-chat, para não remover campos incompatíveis silenciosamente.
  • Trata dicas de erro Agent-First como did_you_mean, suggestions, retry_after e recommended_request.

​
Instalação

Use o comando canônico de instalação não interativa:
npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
Isso instala o skill compartilhado tokenlab-api-integration a partir do repositório TokenLab skills.Se sua ferramenta não suporta o installer, copie skills/tokenlab-api-integration/ do repositório para o diretório compartilhado de skills ou rules da ferramenta.

​
Atualizar instalações existentes

Se você instalou o skill antes da limpeza do repositório TokenLab, execute o mesmo comando novamente. O pacote público atual é menor e não depende mais de scripts locais de busca gerados.

​
Verificar instalação

Pergunte ao seu coding agent: 
Quais skills estão disponíveis?
Se tokenlab-api-integration aparecer, a instalação foi concluída.

​
Obtenha sua API Key

1

Visite TokenLab

Acesse tokenlab.sh
2

Entre

Crie uma conta ou faça login
3

Obtenha a API Key

Abra Dashboard → API Keys e crie uma nova key
4

Copie a key

Sua key começa com sk-.... Guarde-a com segurança.
Não cole API keys em prompts ou arquivos-fonte. O skill deve perguntar qual variável de ambiente usar e gerar código que leia a key dessa variável.

​
Fluxo recomendado para Agent

  1. Comece pelo menor exemplo funcional que corresponda à linguagem e à família de API solicitadas.
  2. Quando a escolha do modelo estiver em aberto, chame /v1/models ou https://api.tokenlab.sh/llms.txt antes de fixar um modelo.
  3. Para trabalho não-chat, chame /v1/models?recommended_for=<scene> onde <scene> é image, video, music, 3d, tts, stt, embedding, rerank ou translation.
  4. Antes de alterar uma solicitação não-chat com falha, leia /v1/models/:model e alinhe supported_operations, supported_parameters, request_endpoint, request_endpoint_by_operation, request_shape_mode e recommended_request.
  5. Se a API retornar um erro Agent-First, use os campos estruturados para corrigir a solicitação e tente novamente apenas se o erro for retryable.

​
Exemplo mínimo de chat

Este exemplo usa o SDK Python da OpenAI com a base URL da TokenLab: 
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)
Execute com: 
pip install openai
export TOKENLAB_API_KEY="sk-your-api-key"
python app.py

​
Descoberta de modelos e contratos

Prefira descoberta ao vivo em vez de listas antigas empacotadas: 
# Visão geral da API legível por máquina
curl https://api.tokenlab.sh/llms.txt

# Listar modelos
curl "https://api.tokenlab.sh/v1/models" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?category=image" -H "Authorization: Bearer sk-KEY"

# Listas ranqueadas para não-chat
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=translation" -H "Authorization: Bearer sk-KEY"

# Ler o detalhes do modelo de um modelo antes de tentar novamente solicitações não-chat
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# Detalhe apenas de preços
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"

​
Dicas de roteamento nativo

O caminho compatível com OpenAI /v1 é o padrão para exemplos comuns de chat, Responses, imagem, embedding, áudio e rerank. Use rotas nativas Anthropic ou Gemini apenas quando a solicitação exigir comportamento específico do provedor ou quando a TokenLab retornar X-TokenLab-Native-Endpoint como dica de otimização. 
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages

​
Recuperação de erros Agent-First

Os erros incluem campos que coding agents podem analisar sem raspar a documentação:
ErroCampos úteisAção do agent
Nome de modelo incorretodid_you_mean, suggestions, hintTente novamente com o modelo corrigido ou uma alternativa sugerida
Saldo insuficientebalance_usd, estimated_cost_usd, suggestionsPeça aprovação ou mude para um modelo acessível
Limite de taxa ou indisponibilidade temporáriaretryable, retry_after, alternativesAguarde, tente novamente ou escolha uma alternativa listada
Contrato não-chat incompatívelsupported_operations, supported_parameters, request_endpoint, request_endpoint_by_operation, request_shape_mode, recommended_requestReconstrua a solicitação a partir dos detalhes do modelo e aplique return a clear error a campos que mudem a intenção

​
Famílias de API compatíveis

FamíliaCaminho principal
Chat e Responses/v1/chat/completions, /v1/responses
Mensagens nativas Claude/v1/messages
Solicitações nativas Gemini/v1beta/models/{model}:generateContent
Imagens/v1/images/generations, /v1/images/edits
Vídeo/v1/videos/generations
Música/v1/music/generations
Worlds/v1/worlds/generations mais endpoints de status world e media asset
3D/v1/3d/generations
Áudio/v1/audio/speech, /v1/audio/transcriptions, /v1/audio/translations
Realtime/v1/realtime?model={model}
Embeddings e rerank/v1/embeddings, /v1/rerank
Tradução de texto/v1/translations

​
Boas práticas

Segurança da API Key

Use variáveis de ambiente e chamadas server-side. Nunca exponha keys no código frontend.

Contrato primeiro para não-chat

Leia /v1/models?recommended_for=... e /v1/models/:model antes de tentar novamente solicitações de imagem, vídeo, música, 3D, tradução, áudio, embedding ou rerank.

Menor exemplo executável

Gere uma chamada funcional antes de adicionar abstrações, filas ou fluxos de UI.

Use dicas estruturadas

Analise did_you_mean, retry_after, alternatives e recommended_request antes de alterar o código.

​
FAQ

Mencione “TokenLab” ou “TokenLab API” na solicitação, por exemplo: Use TokenLab para adicionar geração de imagens ao meu app Node.js.
Qualquer coding agent que suporte diretórios compartilhados de skill ou rules pode usar a pasta. O installer skills trata agents suportados automaticamente.
Execute novamente o comando de instalação. Ele atualiza a cópia local a partir do repositório público canônico.
npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y

​
Recursos

Agent-First API

Dicas de erro estruturadas e comportamento de recuperação

Documentação da API

Configuração por endpoint e API Reference

Modelos

Veja modelos disponíveis

llms.txt

Visão geral da API legível por máquina para agents
Dúvidas? Use GitHub Issues ou contate support@tokenlab.sh.