> ## 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 integración de la API de TokenLab

> Instala el skill mantenido de integración de la API de TokenLab y enseña a los coding agents a descubrir modelos, leer contratos públicos y recuperarse de errores de API.

<Note>
  Esta página documenta el skill compartido mantenido `tokenlab-api-integration`. La distribución canónica vive en [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills), donde el repositorio público conserva intencionalmente solo este skill.
</Note>

<Note>
  Usa esta página para instalar el skill y guiar el flujo del agent. Para configuración por endpoint, usa la página dedicada de SDK, cliente o referencia API.
</Note>

## Qué hace el skill

* Genera ejemplos mínimos ejecutables para chat, imagen, audio, video, traducción y otras familias de API de TokenLab.
* Usa `https://api.tokenlab.sh/v1` para clientes compatibles con OpenAI y explica cuándo cambiar a rutas nativas de Anthropic o Gemini.
* Descubre modelos con `/v1/models`, `/llms.txt` y listas `recommended_for` en lugar de adivinar desde listas obsoletas.
* Lee los detalhes do modelo de un modelo antes de reintentar solicitudes no-chat para no eliminar silenciosamente campos no compatibles.
* Gestiona pistas de error Agent-First como `did_you_mean`, `suggestions`, `retry_after` y `recommended_request`.

## Instalación

<Note>
  Usa el comando canónico de instalación no interactiva:

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

  Esto instala el skill compartido `tokenlab-api-integration` desde el repositorio TokenLab skills.

  Si tu herramienta no soporta el installer, copia `skills/tokenlab-api-integration/` del repositorio al directorio compartido de skills o rules de tu herramienta.
</Note>

### Actualizar instalaciones existentes

Si instalaste el skill anteriormente, vuelve a ejecutar el mismo comando para actualizar al paquete público actual.

### Verificar instalación

Pregunta a tu coding agent:

```
¿Qué skills están disponibles?
```

Si ves `tokenlab-api-integration`, la instalación fue correcta.

## Obtén tu API Key

<Steps>
  <Step title="Visita TokenLab">
    Ve a [tokenlab.sh](https://tokenlab.sh)
  </Step>

  <Step title="Inicia sesión">
    Crea una cuenta o inicia sesión
  </Step>

  <Step title="Obtén la API Key">
    Abre [Dashboard → API Keys](https://tokenlab.sh/dashboard/api) y crea una nueva key
  </Step>

  <Step title="Copia la key">
    Tu key empieza por `sk-...`. Guárdala de forma segura.
  </Step>
</Steps>

<Tip>
  No pegues API keys en prompts ni archivos fuente. El skill debe preguntar qué variable de entorno usar y generar código que lea la key desde esa variable.
</Tip>

## Flujo recomendado para Agent

1. Empieza con el ejemplo funcional más pequeño que coincida con el lenguaje y la familia de API solicitados.
2. Si la elección de modelo está abierta, llama a `/v1/models` o `https://api.tokenlab.sh/llms.txt` antes de fijar un modelo.
3. Para trabajo no-chat, llama a `/v1/models?recommended_for=<scene>` donde `<scene>` es `image`, `video`, `music`, `3d`, `tts`, `stt`, `embedding`, `rerank` o `translation`.
4. Antes de cambiar una solicitud no-chat fallida, lee `/v1/models/:model` y alinea `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode` y `recommended_request`.
5. Si la API devuelve un error Agent-First, usa los campos estructurados para corregir la solicitud y reintenta solo si el error es retryable.

## Ejemplo mínimo de chat

Este ejemplo usa el SDK Python de OpenAI con la base URL de 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)
```

Ejecútalo con:

```bash theme={null}
pip install openai
export TOKENLAB_API_KEY="sk-your-api-key"
python app.py
```

## Descubrimiento de modelos y contratos

Prefiere descubrimiento en vivo antes que listas empaquetadas obsoletas:

```bash theme={null}
# Resumen API legible 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 cortas clasificadas para no-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"

# Leer los detalhes do modelo de un modelo antes de reintentar solicitudes no-chat
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# Detalle solo de precios
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"
```

## Pistas de enrutamiento nativo

La ruta compatible con OpenAI `/v1` es la opción predeterminada para ejemplos comunes de chat, Responses, imagen, embedding, audio y rerank. Usa rutas nativas de Anthropic o Gemini solo cuando la solicitud necesite comportamiento específico del proveedor o TokenLab devuelva `X-TokenLab-Native-Endpoint` como pista de optimización.

```
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages
```

## Recuperación de errores Agent-First

Los errores incluyen campos que los coding agents pueden analizar sin extraer la documentación:

| Error                                      | Campos útiles                                                                                                                                    | Acción del agent                                                                                                |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| Nombre de modelo incorrecto                | `did_you_mean`, `suggestions`, `hint`                                                                                                            | Reintenta con el modelo corregido o una alternativa sugerida                                                    |
| Saldo insuficiente                         | `balance_usd`, `estimated_cost_usd`, `suggestions`                                                                                               | Pide aprobación o cambia a un modelo asequible                                                                  |
| Límite de tasa o indisponibilidad temporal | `retryable`, `retry_after`, `alternatives`                                                                                                       | Espera, reintenta o elige una alternativa listada                                                               |
| Contrato no-chat incompatible              | `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request` | Reconstruye la solicitud desde los detalhes do modelo y return a clear error en campos que cambien la intención |

## Familias de API compatibles

| Familia                    | Ruta principal                                                           |
| -------------------------- | ------------------------------------------------------------------------ |
| Chat y Responses           | `/v1/chat/completions`, `/v1/responses`                                  |
| Mensajes nativos Claude    | `/v1/messages`                                                           |
| Solicitudes nativas Gemini | `/v1beta/models/{model}:generateContent`                                 |
| Imágenes                   | `/v1/images/generations`, `/v1/images/edits`                             |
| Video                      | `/v1/videos/generations`                                                 |
| Música                     | `/v1/music/generations`                                                  |
| Worlds                     | `/v1/worlds/generations` más endpoints de estado world y media asset     |
| 3D                         | `/v1/3d/generations`                                                     |
| Audio                      | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| Realtime                   | `/v1/realtime?model={model}`                                             |
| Embeddings y rerank        | `/v1/embeddings`, `/v1/rerank`                                           |
| Traducción de texto        | `/v1/translations`                                                       |

## Buenas prácticas

<CardGroup cols={2}>
  <Card title="Seguridad de API Key" icon="shield">
    Usa variables de entorno y llamadas del lado servidor. Nunca expongas keys en código frontend.
  </Card>

  <Card title="Contrato primero para no-chat" icon="file-code">
    Lee `/v1/models?recommended_for=...` y `/v1/models/:model` antes de reintentar solicitudes de imagen, video, música, 3D, traducción, audio, embedding o rerank.
  </Card>

  <Card title="Ejemplo ejecutable mínimo" icon="terminal">
    Genera una llamada funcional antes de añadir abstracciones, colas o flujos de UI.
  </Card>

  <Card title="Usa pistas estructuradas" icon="rotate-cw">
    Analiza `did_you_mean`, `retry_after`, `alternatives` y `recommended_request` antes de cambiar el código.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="¿El skill no se activa automáticamente?">
    Menciona “TokenLab” o “TokenLab API” en la solicitud, por ejemplo: `Usa TokenLab para agregar generación de imágenes a mi app Node.js`.
  </Accordion>

  <Accordion title="¿Qué coding agents son compatibles?">
    Cualquier coding agent que soporte directorios compartidos de skill o rules puede usar la carpeta. El installer `skills` gestiona automáticamente los agents compatibles.
  </Accordion>

  <Accordion title="¿Cómo actualizo el skill?">
    Vuelve a ejecutar el comando de instalación. Actualiza la copia local desde el repositorio 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="/es/guides/agent-first-api">
    Pistas estructuradas de error y comportamiento de recuperación
  </Card>

  <Card title="Documentación API" icon="book" href="https://docs.tokenlab.sh">
    Configuración por endpoint y API Reference
  </Card>

  <Card title="Modelos" icon="sparkles" href="https://tokenlab.sh/es/models">
    Explora modelos disponibles
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    Resumen API legible por máquina para agents
  </Card>
</CardGroup>

<Info>
  ¿Preguntas? Usa [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues) o contacta a [support@tokenlab.sh](mailto:support@tokenlab.sh).
</Info>