# API Reference — OpenAI / Anthropic / Gemini Protocols

Source: https://ofox.io/docs/api

OfoxAI offers three protocol-compatible API access methods, fully compatible with each provider's official SDK.

**Protocol recommendation:** for the OpenAI protocol, we recommend the [Responses API](https://ofox.io/docs/api/openai/responses) for better native Prompt Caching; for Claude models, we recommend the [native Anthropic protocol](https://ofox.io/docs/api/anthropic/messages) for the full feature set and native caching.

## Base URL

| Protocol | Base URL | Description |
|----------|----------|-------------|
| **OpenAI Compatible** | `https://api.ofox.io/v1` | Compatible with OpenAI SDK, supports all models |
| **Anthropic Native** | `https://api.ofox.io/anthropic` | Compatible with Anthropic SDK, native Claude experience |
| **Gemini Native** | `https://api.ofox.io/gemini` | Compatible with Google GenAI SDK |

## Authentication

All protocols use a unified OfoxAI API Key, but the header format varies by protocol:

| Protocol | Header | Format |
|----------|--------|--------|
| OpenAI | `Authorization` | `Bearer sk-xxx` |
| Anthropic | `x-api-key` | `sk-xxx` |
| Gemini | `x-goog-api-key` | `sk-xxx` |

See [API Key Setup & Usage](https://ofox.io/docs/develop/authentication) for details.

## Available Endpoints

### OpenAI Compatible Protocol

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/chat/completions` | POST | Create chat completion |
| `/v1/embeddings` | POST | Create text embeddings |
| `/v1/models` | GET | List available models |
| `/v1/models/{model_id}` | GET | Get model details |
| `/v1/images/generations` | POST | Generate images |

### Anthropic Native Protocol

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/anthropic/v1/messages` | POST | Create Messages |

### Gemini Native Protocol

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/gemini/v1beta/models/{model}:generateContent` | POST | Generate content |
| `/gemini/v1beta/models/{model}:streamGenerateContent` | POST | Stream generate content |

### Typed Decisions

Make yes/no, single-choice, and scoring judgments on content and get structured answers with probabilities. See the [Decisions API docs](https://ofox.io/docs/api/decisions).

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/decisions` | POST | Unified format; also callable with the OpenAI SDK |
| `/openai/v1/decisions` | POST | Same as above, for OpenAI SDK setups whose base URL is `/openai/v1` |
| `/typesafe/v1/systemone` | POST | Official TypeSafe format, compatible with the TypeSafe SDK |

### Video Generation (OpenRouter-compatible)

Unified async video generation API. See the [Video API docs](https://ofox.io/docs/api/videos).

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/videos` | POST | [Create a video generation task](https://ofox.io/docs/api/videos/create) |
| `/v1/videos/{id}` | GET | [Get task status and result](https://ofox.io/docs/api/videos/retrieve) |
| `/v1/videos/{id}` | DELETE | [Cancel a task](https://ofox.io/docs/api/videos/cancel) |

### OfoxAI OpenAPI (Account)

Protocol-agnostic platform endpoints, authenticated with the OfoxAI API Key.

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/user/balance` | GET | [Balance query](https://ofox.io/docs/api/openapi/balance), compatible with cc-switch |

## Rate Limits

OfoxAI uses pay-as-you-go pricing with a unified rate policy for all users:

| Limit | Quota |
|-------|-------|
| RPM (requests/minute) | 100 (team-aggregated) |
| TPM (tokens/minute) | Unlimited |

RPM is aggregated at the team level — multiple API Keys under the same team share a single quota. If you need a higher RPM quota, contact [hi@ofox.ai](mailto:hi@ofox.ai) to request an adjustment.

When rate-limited, the API returns `429 Too Many Requests` with the following response headers:

```http
x-ratelimit-limit-requests: 100
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 1s
```

## Error Codes

All protocols return unified HTTP status codes:

| Status Code | Description | Common Causes |
|-------------|-------------|---------------|
| `200` | Success | — |
| `400` | Bad Request | Invalid parameters, missing required fields |
| `401` | Unauthorized | Invalid or expired API Key |
| `403` | Forbidden | Account lacks access to the model |
| `404` | Not Found | Incorrect model ID |
| `429` | Rate Limited | Exceeded rate limit |
| `500` | Server Error | Internal error, please retry |
| `502` | Upstream Error | Model provider service issue |
| `503` | Service Unavailable | Under maintenance |

### Error Response Format

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API Key is invalid. Please check and try again.",
    "type": "authentication_error"
  }
}
```

## OfoxAI Extension Parameters

OfoxAI provides extension parameters on top of standard protocols for advanced routing and fallback control:

```json
{
  "model": "openai/gpt-6.1-sol",
  "messages": [...],
  "extra_body": {
    "provider": {
      "fallback": ["anthropic/claude-sonnet-5.5", "google/gemini-3.8-flash"]
    }
  }
}
```

`provider` must be placed inside `extra_body` in the request body; placing it at the top level returns `400`. See [Provider Routing](https://ofox.io/docs/develop/advanced/provider-routing) and [Fallback](https://ofox.io/docs/develop/advanced/fallback) for details.