API Overview

HaoAI offers four API protocol families: OpenAI-compatible, Anthropic native, Grok / xAI, and Gemini native.

Base URL

Protocol	Base URL	Description
OpenAI Compatible	`https://api.hao.ai/v1`	Compatible with OpenAI SDK, supports all models
Anthropic Native	`https://api.hao.ai/anthropic`	Compatible with Anthropic SDK, native Claude experience
Grok / xAI Protocol	`https://api.hao.ai/grok`	Grok / xAI route with an xAI OpenAI-compatible text JSON/SSE shape
Gemini Native	`https://api.hao.ai/gemini`	Compatible with Google GenAI SDK

Authentication

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

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

See the Authentication guide for details.

Available Endpoints

OpenAI Compatible Protocol

Endpoint	Method	Description
`/v1/chat/completions`	POST	Create chat completion
`/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

Grok / xAI Protocol

Endpoint	Method	Description
`/grok/v1/chat/completions`	POST	Create a Grok chat completion. See Chat Completions
`/grok/v1/responses`	POST	Create a Grok Responses API response. See Responses
`/grok/v1/models`	GET	List available Grok models. See Models
`/grok/v1/models/{model_id}`	GET	Get a Grok model detail

Gemini Native Protocol

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

HaoAI OpenAPI (Platform)

Protocol-agnostic platform endpoints; see each endpoint’s documentation for its authentication method.

Endpoint	Method	Description
`/v1/user/balance`	GET	Balance query, compatible with cc-switch, authenticated with the HaoAI API Key
`hao.ai/api/provider/pricing`	GET	Real-time pricing, hvoy-compatible, HMAC-signed or public access

Rate Limits

HaoAI 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 support@hao.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 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


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

HaoAI Extension Parameters

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


{
  "model": "openai/gpt-4o",
  "messages": [...],
  "provider": {
    "routing": "cost",
    "fallback": ["anthropic/claude-sonnet-4.6", "grok/grok-4.5"]
  }
}

See Provider Routing and Fallback for details.