TokenLab Native Endpoints

TokenLab Native Endpoints

Use this skill when a user needs provider-native behavior, non-chat APIs, or migration guidance beyond OpenAI-compatible /v1/chat/completions.

What this skill should deliver

• A clear endpoint choice and why it fits the request.
• A minimal request example with the correct base URL and auth header.
• A note on when OpenAI-compatible chat remains the simpler path.
• A fail-closed contract check for non-chat or provider-native request shapes.
• A recovery path when TokenLab returns a native endpoint hint or contract error.

Endpoint families

• OpenAI-compatible chat: POST https://api.tokenlab.sh/v1/chat/completions
• OpenAI Responses: POST https://api.tokenlab.sh/v1/responses
• Anthropic Messages: POST https://api.tokenlab.sh/v1/messages
• Gemini native generate content: POST https://api.tokenlab.sh/v1beta/models/{model}:generateContent
• Model catalog: GET https://api.tokenlab.sh/v1/models
• Task-specific model shortlist: GET https://api.tokenlab.sh/v1/models?recommended_for=
• Model contract: GET https://api.tokenlab.sh/v1/models/:model

Preferred approach

1. Start with OpenAI-compatible chat unless the user needs a native contract, non-chat API, or provider-specific behavior.
2. If a previous response includes X-TokenLab-Hint or X-TokenLab-Native-Endpoint, treat it as routing evidence and prefer the exact native route in the header.
3. For Anthropic-style requests, use /v1/messages and preserve Anthropic request semantics instead of converting blindly.
4. For Gemini-style requests, preserve Gemini content parts, roles, tools, and generation config when the user explicitly needs Gemini-native behavior.
5. For media/audio/embedding/rerank/translation requests, inspect GET /v1/models/:model before changing request parameters.

Output format

• One sentence naming the chosen endpoint.
• One runnable code block or cURL block.
• One short explanation of why this endpoint fits.
• One recovery note naming the catalog or contract endpoint to check if the call fails.

Avoid

• Do not flatten native Anthropic or Gemini request semantics into generic OpenAI chat unless the user explicitly accepts that tradeoff.
• Do not remove unsupported fields just to make validation pass when doing so would change output, safety, billing, or response guarantees.
• Do not hardcode media request shapes without inspecting the model contract.
• Do not expose private TokenLab routing, channel, or physical provider internals.

Edge Cases

• If the model supports both OpenAI-compatible and native routes, pick the simpler path unless the user needs native behavior.
• If the endpoint hint conflicts with the user's explicit requirement, explain the tradeoff and ask for confirmation before changing semantics.
• If a request fails with a contract error, use supported operations and recommended request fields to repair it.