API reference

The Yaha gateway exposes an OpenAI-compatible surface at https://gateway.yahagateway.io/v1 or your assigned gateway URL. Authenticate with a Yaha project key:

Authorization: Bearer yaha.YOUR_PROJECT_KEY

Do not send provider API keys from your application. Use a model ID that is enabled for your project.

Base URL

https://gateway.yahagateway.io/v1

OpenAI-compatible SDKs usually call this setting baseURL, base_url, or OPENAI_BASE_URL.

Supported endpoints

Text generation:

POST /v1/chat/completions
POST /v1/responses
POST /v1/messages
POST /v1/completions

Other model-backed endpoints:

POST /v1/embeddings
POST /v1/images/generations
POST /v1/images/edits
POST /v1/audio/speech
POST /v1/audio/transcriptions
POST /v1/moderations
POST /v1/rerank
POST /v1/videos

Discovery and reporting:

GET /v1/models
GET /v1/generation?id=REQUEST_ID

Additional /v1/* provider routes may pass through when supported by the selected provider and project configuration.

Request body

Field	Type	Description
`model`	string	Primary model ID, alias, or provider-prefixed slug enabled for your project
`models`	string[]	Optional fallback model list, tried in order when failover is enabled
`route`	string	Set to `"fallback"` to enable automatic failover on provider 429/5xx responses
`provider`	object	Per-request provider preferences (see Provider preferences)
`messages`	array	Standard OpenAI chat messages for chat-compatible endpoints
`input`	string or array	Standard Responses API input for `/v1/responses`
`stream`	boolean	Set to `true` for Server-Sent Events on compatible endpoints

Routing-only fields such as models, route, and provider are used by the gateway and are not sent to the model provider.

Streaming

For chat and responses-style requests, set "stream": true. The gateway returns Server-Sent Events and preserves standard OpenAI-compatible streaming behavior.

App attribution headers

Optional headers can help identify requests in your own reports and logs:

X-Request-ID: supply your own request ID for traceability and later lookup with /v1/generation
X-Environment or X-LLM-Environment: label requests as prod, staging, dev, or another environment
HTTP-Referer or Referer: application URL
X-Title or X-OpenRouter-Title: application name

Only send metadata that is safe for your organization to retain in request logs.

Usage object

When usage-cost injection is enabled for the project, successful non-streaming responses include a standard usage object with token counts and estimated cost:

{
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 50,
    "total_tokens": 150,
    "cost": 0.00042,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}

For streaming responses, usage may be available in the final stream event or through the generation lookup endpoint after the request completes.

Common status codes

400: malformed JSON, missing model, unsupported model for the endpoint, or no routable model
401: missing or invalid project key
403: project key is not authorized, plan is inactive, or access policy blocked the request
402: billing or balance requirement not met
429: request was rate limited
502: provider credentials or upstream provider request failed
503: gateway project configuration is temporarily unavailable

Models list: GET /v1/models
Generation lookup: GET /v1/generation?id=

API Reference