Setting HTTP Headers

Introduction

HTTP headers play a crucial role in API communication, providing metadata about the request and response, handling authentication, and controlling content negotiation. When interacting with the A4F API, certain standard headers are required, and there might be optional A4F-specific headers for advanced functionalities.

Standard Headers

The following standard HTTP headers are essential for making requests to the A4F API:

• Authorization:

  This header is used to authenticate your API request. You must provide your A4F API key as a Bearer token. Format: Authorization: Bearer YOUR_A4F_API_KEY. For more details, see the Authentication documentation.

• Content-Type:

  For POST requests (like chat completions), this header must be set to application/json to indicate that the request body is in JSON format.

POST /v1/chat/completions HTTP/1.1
Host: api.a4f.co
Authorization: Bearer YOUR_A4F_API_KEY
Content-Type: application/json

{
  "model": "provider-X/model-name",
  "messages": [{"role": "user", "content": "Hello!"}]
}

A4F-Specific Headers (Conceptual)

A4F might introduce custom headers (often prefixed with X-A4F-) for specialized features or to control platform-specific behavior. These headers are optional and typically used for advanced scenarios.

Potential conceptual examples of A4F-specific headers could include:

• Caching Control (e.g., X-A4F-Cache-Control):

  To suggest caching preferences for responses (e.g., read, write, read-write, bypass). This feature would depend on A4F implementing a caching layer.

• Metadata Passthrough (e.g., X-A4F-Metadata-UserID):

  To pass your application's internal end-user ID or other metadata through A4F for logging or analytics purposes on your end, or potentially for display on A4F dashboards if supported. This is distinct from the user parameter in the request body.

• Routing Hints (e.g., X-A4F-Route-Preference):

  While provider selection is done via model prefix, future enhancements might allow hints like latency or cost if A4F implements dynamic routing for ambiguous model requests (currently, ambiguous requests without provider prefixes are errors).

# These are conceptual examples and may not be currently implemented
# or may have different names/functionality.
# Always refer to the latest official A4F documentation.

X-A4F-Cache-Control: read-write # Example: For controlling cache behavior
X-A4F-Metadata-UserID: your-app-user-id-123 # Example: For passing end-user identifiers
X-A4F-Route-Preference: latency # Example: For hinting routing preference

If and when such headers are officially supported, their usage will be detailed in the relevant sections of the A4F API documentation (e.g., API Overview or specific feature guides).

Passthrough Headers

A4F may pass certain standard or common non-conflicting headers through to the underlying LLM providers if they are relevant and supported by those providers. However, do not rely on arbitrary header passthrough without explicit documentation from A4F. Headers like `Authorization` are consumed by A4F and will not be passed directly to the end provider.

Implementation Examples

Here’s how you would typically set headers in your HTTP client when making direct API calls (not using an SDK that abstracts this).

import requests
import json

A4F_API_KEY = "YOUR_A4F_API_KEY"
A4F_API_ENDPOINT = "https://api.a4f.co/v1/chat/completions"

headers = {
    "Authorization": f"Bearer {A4F_API_KEY}",
    "Content-Type": "application/json",
    # Add any conceptual A4F-specific headers here if applicable
    # "X-A4F-Metadata-UserID": "user_abc_123" 
}

payload = {
    "model": "provider-1/chatgpt-4o-latest",
    "messages": [{"role": "user", "content": "Hello with headers!"}]
}

response = requests.post(A4F_API_ENDPOINT, headers=headers, json=payload)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}", response.text)

async function callA4FApiWithHeaders() {
  const a4fApiKey = "YOUR_A4F_API_KEY";
  const a4fApiEndpoint = "https://api.a4f.co/v1/chat/completions";

  const headers: HeadersInit = {
    "Authorization": `Bearer ${a4fApiKey}`,
    "Content-Type": "application/json",
    // Add any conceptual A4F-specific headers here if applicable
    // "X-A4F-Metadata-UserID": "user_xyz_789"
  };

  const body = JSON.stringify({
    model: "provider-1/chatgpt-4o-latest",
    messages: [{ role: "user", content: "Hello with headers!" }],
  });

  try {
    const response = await fetch(a4fApiEndpoint, {
      method: "POST",
      headers: headers,
      body: body,
    });

    if (!response.ok) {
      const errorData = await response.json();
      console.error(`API Error (${response.status}):`, errorData);
      return;
    }
    
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error("Request failed:", error);
  }
}

callA4FApiWithHeaders();

If using an OpenAI SDK, custom headers beyond `Authorization` and `Content-Type` might need to be configured via specific options in the client setup or by customizing the request mechanism, as the SDK primarily focuses on OpenAI's standard parameters.

Security Considerations

Be cautious about the information you include in custom headers, especially if they are logged by intermediate systems or providers. Avoid sending sensitive personal data or secrets through headers unless explicitly required and documented by A4F for a secure purpose.