API Overview

Authentication

All API requests to A4F must be authenticated using a Bearer token. Your A4F API key should be included in the Authorization header.

Authorization: Bearer YOUR_A4F_API_KEY

You can generate and manage your API keys from the API Keys section of your dashboard. For more details, see our Authentication guide.

Requests

Completions Request Format

Here is the basic request schema. This will be the body of your POST request to the /v1/chat/completions endpoint.

{
  "model": "provider-X/model-name",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello! What can you do?" }
  ],
  "temperature": 0.7,
  "max_tokens": 150,
  "stream": false
  // ... other standard OpenAI parameters
}

Key fields:

• model (required): The ID of the model to use. For A4F, this typically follows the format provider-X/actual-model-id. Refer to our Models page for a list of available models and their identifiers, and the Provider Routing documentation for how A4F handles different providers.
• messages (required): A list of message objects, where each object has a role (e.g., "system", "user", or "assistant") and content.
• Other standard OpenAI parameters like temperature, max_tokens, stream, tools, tool_choice, etc., are generally supported and passed through to the underlying model provider.

For a complete list of supported parameters and their descriptions, please see the Parameters documentation.

Headers

Besides the Authorization header, you must include:

• Content-Type: application/json

curl https://api.a4f.co/v1/chat/completions \
  -H "Authorization: Bearer YOUR_A4F_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider-1/chatgpt-4o-latest",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Streaming

To stream responses, set "stream": true in your request body. A4F supports streaming via Server-Sent Events (SSE). For more details on handling streamed responses, refer to our Streaming documentation.

Tool Calling

A4F supports tool calling (function calling) for models that offer this capability. You can define tools in the tools parameter and guide the model's tool selection with tool_choice. Check the Tool Calling documentation for examples and provider compatibility.

Responses

Completions Response Format

A successful API call will return a 200 OK HTTP status code with a JSON body that is compatible with the OpenAI Chat Completions API response schema.

{
  "id": "chatcmpl-xxxxxxxxxxxxxxxxxxxxxxx",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "provider-X/model-name", // The model used for this completion
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello there! I am an AI assistant. How can I help you today?"
      },
      "finish_reason": "stop" // e.g., "stop", "length", "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
  // "system_fingerprint": "fp_xxxxxxxxxx" // May be present depending on the model
}

The model field in the response will reflect the full A4F model string you requested (e.g., provider-X/model-name). The usage object provides token counts for the request.

Finish Reason

The finish_reason in each choice indicates why the model stopped generating tokens.

[
  "stop",      // API returned a complete message.
  "length",    // Incomplete model output due to max_tokens parameter or token limit.
  "tool_calls",// Model decided to call a tool.
  "content_filter", // Omitted content due to a flag from our content filters.
  "null"       // API response still in progress or incomplete.
]

Error Handling

If an API request fails, A4F will return an appropriate HTTP status code (e.g., 400, 401, 403, 429, 500) and a JSON body containing error details. For a comprehensive list of error codes and their meanings, please see our Errors documentation.

Usage and Stats

A4F automatically tracks your API usage, including the number of requests and tokens processed (prompt and completion).

• The usage object in the API response provides token counts for that specific completion.
• You can view your cumulative usage statistics, current plan details, and API key status on your Dashboard. This information is fetched from A4F's backend services.

A4F does not currently offer a public API endpoint to query usage statistics programmatically on a per-generation ID basis. All account-level usage is aggregated and presented on your dashboard.

Rate Limits

API rate limits (e.g., Requests Per Minute - RPM, Requests Per Day - RPD) are determined by your active subscription plan. If you exceed these limits, you will receive a 429 Too Many Requests error.

You can find details about the rate limits for each plan on our Pricing page and specific limits applicable to your account on the Dashboard. For more general information, see Limits.