Skip to Content
API referenceAPI Overview

API Overview

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 for better native Prompt Caching; for Claude models, we recommend the native Anthropic protocol for the full feature set and native caching.

Base URL

ProtocolBase URLDescription
OpenAI Compatiblehttps://api.ofox.io/v1Compatible with OpenAI SDK, supports all models
Anthropic Nativehttps://api.ofox.io/anthropicCompatible with Anthropic SDK, native Claude experience
Gemini Nativehttps://api.ofox.io/geminiCompatible with Google GenAI SDK

Authentication

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

ProtocolHeaderFormat
OpenAIAuthorizationBearer sk-xxx
Anthropicx-api-keysk-xxx
Geminix-goog-api-keysk-xxx

See API Key Setup & Usage for details.

Available Endpoints

OpenAI Compatible Protocol

EndpointMethodDescription
/v1/chat/completionsPOSTCreate chat completion
/v1/embeddingsPOSTCreate text embeddings
/v1/modelsGETList available models
/v1/models/{model_id}GETGet model details
/v1/images/generationsPOSTGenerate images

Anthropic Native Protocol

EndpointMethodDescription
/anthropic/v1/messagesPOSTCreate Messages

Gemini Native Protocol

EndpointMethodDescription
/gemini/v1beta/models/{model}:generateContentPOSTGenerate content
/gemini/v1beta/models/{model}:streamGenerateContentPOSTStream 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.

EndpointMethodDescription
/v1/decisionsPOSTUnified format; also callable with the OpenAI SDK
/openai/v1/decisionsPOSTSame as above, for OpenAI SDK setups whose base URL is /openai/v1
/typesafe/v1/systemonePOSTOfficial TypeSafe format, compatible with the TypeSafe SDK

Video Generation (OpenRouter-compatible)

Unified async video generation API. See the Video API docs.

EndpointMethodDescription
/v1/videosPOSTCreate a video generation task
/v1/videos/{id}GETGet task status and result
/v1/videos/{id}DELETECancel a task

OfoxAI OpenAPI (Account)

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

EndpointMethodDescription
/v1/user/balanceGETBalance query, compatible with cc-switch

Rate Limits

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

LimitQuota
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 to request an adjustment.

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

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 CodeDescriptionCommon Causes
200Success—
400Bad RequestInvalid parameters, missing required fields
401UnauthorizedInvalid or expired API Key
402Payment Requiredinsufficient_credits, spending_limit_exceeded
403Forbiddenip_not_allowed, model_not_allowed (blocked by an access rule) or no access; see Error handling
404Not FoundIncorrect model ID
429Rate LimitedExceeded rate limit
500Server ErrorInternal error, please retry
502Upstream ErrorModel provider service issue
503Service UnavailableUnder maintenance

Error Response Format

{ "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:

{ "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 and Fallback for details.

Last updated on