> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# ✨ Skill de integração da API TokenLab

> Instale o skill mantido de integração da API TokenLab e ensine coding agents a descobrir modelos, ler contratos públicos e se recuperar de erros da API.

<Note>
  Esta página documenta o skill compartilhado mantido `tokenlab-api-integration`. A distribuição canônica fica em [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills), onde o repositório público mantém intencionalmente apenas este skill.
</Note>

<Note>
  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.
</Note>

## 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

<Note>
  Use o comando canônico de instalação não interativa:

  ```bash theme={null}
  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.
</Note>

### 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

<Steps>
  <Step title="Visite TokenLab">
    Acesse [tokenlab.sh](https://tokenlab.sh)
  </Step>

  <Step title="Entre">
    Crie uma conta ou faça login
  </Step>

  <Step title="Obtenha a API Key">
    Abra [Dashboard → API Keys](https://tokenlab.sh/dashboard/api) e crie uma nova key
  </Step>

  <Step title="Copie a key">
    Sua key começa com `sk-...`. Guarde-a com segurança.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## 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:

```python theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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:

| Erro                                           | Campos úteis                                                                                                                                     | Ação do agent                                                                                                         |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Nome de modelo incorreto                       | `did_you_mean`, `suggestions`, `hint`                                                                                                            | Tente novamente com o modelo corrigido ou uma alternativa sugerida                                                    |
| Saldo insuficiente                             | `balance_usd`, `estimated_cost_usd`, `suggestions`                                                                                               | Peça aprovação ou mude para um modelo acessível                                                                       |
| Limite de taxa ou indisponibilidade temporária | `retryable`, `retry_after`, `alternatives`                                                                                                       | Aguarde, tente novamente ou escolha uma alternativa listada                                                           |
| Contrato não-chat incompatível                 | `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request` | Reconstrua 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ília                     | Caminho 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

<CardGroup cols={2}>
  <Card title="Segurança da API Key" icon="shield">
    Use variáveis de ambiente e chamadas server-side. Nunca exponha keys no código frontend.
  </Card>

  <Card title="Contrato primeiro para não-chat" icon="file-code">
    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.
  </Card>

  <Card title="Menor exemplo executável" icon="terminal">
    Gere uma chamada funcional antes de adicionar abstrações, filas ou fluxos de UI.
  </Card>

  <Card title="Use dicas estruturadas" icon="rotate-cw">
    Analise `did_you_mean`, `retry_after`, `alternatives` e `recommended_request` antes de alterar o código.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="O skill não dispara automaticamente?">
    Mencione “TokenLab” ou “TokenLab API” na solicitação, por exemplo: `Use TokenLab para adicionar geração de imagens ao meu app Node.js`.
  </Accordion>

  <Accordion title="Quais coding agents são suportados?">
    Qualquer coding agent que suporte diretórios compartilhados de skill ou rules pode usar a pasta. O installer `skills` trata agents suportados automaticamente.
  </Accordion>

  <Accordion title="Como atualizo o skill?">
    Execute novamente o comando de instalação. Ele atualiza a cópia local a partir do repositório público canônico.

    ```bash theme={null}
    npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
    ```
  </Accordion>
</AccordionGroup>

## Recursos

<CardGroup cols={2}>
  <Card title="Agent-First API" icon="robot" href="/pt/guides/agent-first-api">
    Dicas de erro estruturadas e comportamento de recuperação
  </Card>

  <Card title="Documentação da API" icon="book" href="https://docs.tokenlab.sh">
    Configuração por endpoint e API Reference
  </Card>

  <Card title="Modelos" icon="sparkles" href="https://tokenlab.sh/pt/models">
    Veja modelos disponíveis
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    Visão geral da API legível por máquina para agents
  </Card>
</CardGroup>

<Info>
  Dúvidas? Use [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues) ou contate [support@tokenlab.sh](mailto:support@tokenlab.sh).
</Info>