TokenLab API Header Hints Help Agents Choose the Right Format

Autonomous agents and multi-model routing systems require predictable, structured outputs to execute downstream code. However, different LLM providers return varying JSON schemas, token usage metadata, and finish reasons.

TokenLab API header hints solve this integration friction. By inspecting HTTP response headers before parsing the payload, your agentic workflows can instantly identify the underlying model family, response format, and schema version. This eliminates expensive trial-and-error parsing and prevents runtime exceptions in production agent pipelines.

Key Takeaways

---

TokenLab Model and Pricing Reference

When routing requests through TokenLab, understanding the cost profile of each target model is critical for budget management. The table below outlines the pricing structure for key models supported by the TokenLab API.

Model Name	Input Price (per MTok)	Output Price (per MTok)	Primary Use Case
deepseek-v4-pro	$0.441176	$0.882353	Low-latency structured reasoning
gemini-3.5-flash	$1.500000	$9.000000	High-speed multimodal tasks
claude-opus-4-8	$5.000000	$25.000000	Complex agentic planning and tool use
gpt-5-pro	$15.000000	$120.000000	Frontier reasoning and code generation
gpt-5-mini	$0.250000	$2.000000	Lightweight routing and classification

Pricing rows are drawn from the TokenLab model directory snapshot used for this refresh. Verify the live rate on the model page before using these numbers in procurement or customer-facing documentation.

---

The Challenge of Multi-Model Output Parsing

When building production agents, you often route tasks to different models depending on complexity. For example, you might route simple classification tasks to gpt-5-mini and complex financial analysis to claude-opus-4-8.

However, each provider formats its response envelope differently:

• OpenAI models return token usage in a usage object with completion_tokens.
• Anthropic models return usage inside a usage object with output_tokens.
• DeepSeek models may include specialized reasoning token fields.

Without header hints, your application must attempt to parse the JSON, check for the existence of specific keys, and handle exceptions when keys are missing. This adds latency and complexity to your codebase.

---

Step-by-Step Implementation: TokenLab API Header Hints

To implement robust parsing, configure your HTTP client to read the custom TokenLab headers. The primary header is X-TokenLab-Format-Hint.

Supported Header Values

Because there is no official public specification for all provider-specific format strings, TokenLab uses a standardized set of format hints. If a specific format hint is not documented for a new model, your integration should fall back to a standard JSON parser.

Header Key	Expected Value	Description
X-TokenLab-Format-Hint	openai-v5	Payload conforms to the OpenAI v5 chat completions schema.
X-TokenLab-Format-Hint	anthropic-v4	Payload conforms to the Anthropic Claude Messages API schema.
X-TokenLab-Format-Hint	deepseek-v4	Payload conforms to the DeepSeek v4 API schema.
X-TokenLab-Model-Alias	The active model identifier	Indicates which specific model processed the request (e.g., gemini-3.5-flash).

Python Implementation Example

Below is a complete Python example demonstrating how to inspect the X-TokenLab-Format-Hint header and route the payload to the correct parser function.

import requests

def handle_openai_format(payload):
    # Parse OpenAI-specific usage and choices
    choices = payload.get("choices", [])
    text = choices[0].get("message", {}).get("content", "") if choices else ""
    usage = payload.get("usage", {})
    prompt_tokens = usage.get("prompt_tokens", 0)
    completion_tokens = usage.get("completion_tokens", 0)
    return {"text": text, "input_tokens": prompt_tokens, "output_tokens": completion_tokens}

def handle_anthropic_format(payload):
    # Parse Anthropic-specific usage and content blocks
    content = payload.get("content", [])
    text = content[0].get("text", "") if content else ""
    usage = payload.get("usage", {})
    input_tokens = usage.get("input_tokens", 0)
    output_tokens = usage.get("output_tokens", 0)
    return {"text": text, "input_tokens": input_tokens, "output_tokens": output_tokens}

def process_tokenlab_request(api_url, headers, payload):
    response = requests.post(api_url, json=payload, headers=headers)

    # Extract the format hint header
    format_hint = response.headers.get("X-TokenLab-Format-Hint")
    model_used = response.headers.get("X-TokenLab-Model-Alias")

    print(f"Request processed by: {model_used}")
    print(f"Detected format hint: {format_hint}")

    response_json = response.json()

    # Route to the correct parser based on the header hint
    if format_hint == "openai-v5":
        return handle_openai_format(response_json)
    elif format_hint == "anthropic-v4":
        return handle_anthropic_format(response_json)
    else:
        # Fallback parser for undocumented or generic formats
        print("Warning: Unknown format hint. Using generic fallback parser.")
        return {"text": str(response_json), "input_tokens": 0, "output_tokens": 0}

Verification and Error Handling

If the X-TokenLab-Format-Hint header is missing or contains an unexpected value, do not crash the application. Implement a fallback parser that attempts to locate common keys like content, text, or choices to extract the completion text. Always log the raw headers and payload to an observability tool for debugging.

---

Related TokenLab Developer Guides

To further optimize your multi-agent infrastructure, explore these implementation guides:

• Learn how to configure fallback models in our agent model fallback routing guide.
• Optimize your token usage tracking with TokenLab dashboard usage exports.
• Secure your first integration with build an AI chatbot with one API key.

---

Frequently Asked Questions

What happens if a model does not have a format hint?

If TokenLab cannot determine a specific format hint for a downstream provider, the X-TokenLab-Format-Hint header will return generic-json. Your application should have a fallback parser configured to handle standard JSON structures in this scenario.

Does inspecting headers add latency to the API call?

No. HTTP headers are sent at the very beginning of the TCP response payload. Inspecting headers in your application code takes microseconds and prevents the CPU overhead of running multiple try-except blocks on the JSON body.

Can I force TokenLab to return a specific format hint?

No. The format hint is a reflection of the underlying model's native response structure. To enforce a single format across all models, you must use TokenLab's normalization middleware, which standardizes all responses to a unified schema.

---

Next Steps

Ready to build resilient multi-agent systems? Start with the TokenLab API format guide, then test the parser against live model responses before wiring it into production.

Read the API format guide