Guides

Anthropic Custom Headers

Overview

This guide demonstrates how to use Pay-i's custom headers with Anthropic's Python SDK to annotate your API requests with important metadata.

Basic Pattern

Anthropic's Python SDK supports Pay-i annotations through the extra_headers parameter:

import os
import anthropic
from payi.lib.helpers import create_headers

# Initialize Anthropic client
client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

# Create headers with your annotations
request_headers = create_headers(
    use_case_name="content_generation",
    user_id="user_456",
    limit_ids=["monthly_anthropic_budget"],
    request_tags=["creative", "blog"]
)

# Apply the headers to your API call
message = client.messages.create(
    model="claude-3-opus-20240229",
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "Write a blog post about AI safety"}
    ],
    extra_headers=request_headers  # Apply the annotations here
)

Proxy Routing Example

When using Proxy Routing, you'll configure Anthropic to route through Pay-i:

import os
import anthropic
from payi.lib.helpers import payi_anthropic_url, create_headers

# API keys (use environment variables in production)
anthropic_key = os.getenv("ANTHROPIC_API_KEY")
payi_key = os.getenv("PAYI_API_KEY")

# Configure Anthropic client to use Pay-i as a proxy
client = anthropic.Anthropic(
    api_key=anthropic_key,
    base_url=payi_anthropic_url(),  # Use Pay-i's URL as the base
    default_headers={"xProxy-api-key": payi_key}  # Authenticate with Pay-i
)

# Create headers for this specific API call
request_headers = create_headers(
    use_case_name="creative_writing",
    user_id="writer_789",
    limit_ids=["creative_team_budget"],
    request_tags=["fiction", "story"]
)

# Make the API call with custom headers
message = client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=1500,
    messages=[
        {"role": "user", "content": "Write a short story about artificial intelligence"}
    ],
    extra_headers=request_headers  # Apply the annotations here
)

# Access Pay-i tracking information from the response
print(f"Request ID: {message.xproxy_result['request_id']}")
print(f"Cost: {message.xproxy_result['cost']}")

System Prompts and Tools

When using Claude with system prompts and tools, the pattern remains the same:

import anthropic
from payi.lib.helpers import create_headers

client = anthropic.Anthropic(api_key="your-anthropic-api-key")

headers = create_headers(
    use_case_name="research_assistant",
    user_id="researcher_123",
    limit_ids=["research_budget"],
    request_tags=["research", "tools"]
)

# Define a tool
calculator_tool = {
    "name": "calculator",
    "description": "Evaluate mathematical expressions.",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "The mathematical expression to evaluate"
            }
        },
        "required": ["expression"]
    }
}

# Use with system prompt and tools
message = client.messages.create(
    model="claude-3-opus-20240229",
    system="You are a helpful research assistant with access to a calculator.",
    messages=[
        {"role": "user", "content": "What is the square root of 144 multiplied by the cube root of 27?"}
    ],
    tools=[calculator_tool],
    max_tokens=1000,
    extra_headers=headers  # Add annotations here
)

For more information about custom headers and how to use them across different providers, see the Custom Headers documentation.