# Zenith API Integration

Machine-readable integration reference for Zenith API clients and coding tools.

- Human docs: https://docs.zenithmarket.dev/
- Legal and support: https://docs.zenithmarket.dev/legal
- Privacy: https://docs.zenithmarket.dev/legal/#privacy
- Terms: https://docs.zenithmarket.dev/legal/#terms
- Support contacts: https://docs.zenithmarket.dev/legal/#contacts
- API key: https://t.me/zenith_service_bot

## Authentication

Use the same Zenith API key for all available text and image endpoints.
Preferred header:

```http
Authorization: Bearer YOUR_ZENITH_API_KEY
```

Compatible API-key headers:

```http
x-api-key: YOUR_ZENITH_API_KEY
x-goog-api-key: YOUR_ZENITH_API_KEY
api-key: YOUR_ZENITH_API_KEY
anthropic-api-key: YOUR_ZENITH_API_KEY
openai-api-key: YOUR_ZENITH_API_KEY
```

## Base URLs And Model Discovery

OpenAI-compatible clients use:

```text
https://api.zenithmarket.dev/v1
```

Claude Code and Anthropic-compatible clients use:

```text
https://api.zenithmarket.dev
```

Do not append `/v1` to the Anthropic-compatible base URL.

Native Google/Gemini-compatible clients use:

```text
https://api.zenithmarket.dev
```

Set this as the custom Gemini Base URL and send the Zenith key in
`x-goog-api-key`. The native routes add `/v1beta` themselves.

Discover the current routeable catalog before selecting a model:

```http
GET https://api.zenithmarket.dev/v1/models
```

Native Gemini clients discover only routeable Gemini models through:

```http
GET https://api.zenithmarket.dev/v1beta/models
```

Model availability, reasoning modes, and prices are dynamic. Use a returned
model ID or the current bot catalog; do not copy a fixed text-model ID or price
from this document.

## Core Routes

```http
POST /v1/chat/completions
POST /v1/responses
POST /v1/messages
POST /v1/messages/count_tokens
GET  /v1beta/models
POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent?alt=sse
GET  /v1/models
GET  /v1/zenith/key/stats
GET  /v1/zenith/key/usage
```

Use the OpenAI-compatible base URL for `chat/completions`, `responses`, image
requests, and most clients. Use `/v1/messages` only for an Anthropic Messages
client.

## Native Gemini Request

Use the native Gemini shape when a client supports a custom Google/Gemini Base
URL. Replace the placeholder with a `baseModelId` returned by
`GET /v1beta/models`.

```bash
curl "https://api.zenithmarket.dev/v1beta/models/YOUR_GEMINI_MODEL_ID_FROM_GET_V1BETA_MODELS:generateContent" \
  -H "x-goog-api-key: YOUR_ZENITH_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "Reply exactly: ok" }]
      }
    ]
  }'
```

The response uses native `candidates[]` and `usageMetadata`. For SSE, call the
same model through `:streamGenerateContent?alt=sse`; each `data:` event contains
a native Gemini response object and there is no OpenAI `[DONE]` marker. Text,
image parts, system instruction, generation settings, and function declarations
are supported. Unsupported Google-hosted tools, cachedContent, non-empty safety
settings, and explicit thinking configuration return a request error instead of
being silently ignored. If the client cannot change Google's Base URL, use its
OpenAI-compatible mode with `https://api.zenithmarket.dev/v1`.

## Zenith Relay In The ChatGPT App

Zenith Relay connects Zenith API to the ChatGPT app through its quick setup
wizard. Once connected, models exposed by the provider can be used directly in
the ChatGPT app, including models that are not part of ChatGPT's built-in
catalog.

## OpenCode

Configure Zenith as a custom OpenAI provider with `@ai-sdk/openai` and the
base URL `https://api.zenithmarket.dev/v1`. This package makes OpenCode send
requests to `POST /v1/responses`; do not use `@ai-sdk/openai-compatible` for
this integration because it selects Chat Completions instead. Add only model
IDs returned by `GET /v1/models`.

## Kilo Code In VS Code

Configure Zenith as an isolated Kilo Code Custom provider. This does not alter
the built-in OpenAI provider or its credentials.

```text
Provider ID: zenith
Display name: Zenith
Provider API: OpenAI Compatible
Base URL: https://api.zenithmarket.dev/v1
API key: YOUR_ZENITH_API_KEY
```

Do not append `/responses` or `/chat/completions` to the Base URL. Select a
model returned by `GET /v1/models`, save the provider, then start a new task.
Kilo sends this Custom provider configuration to `/v1/chat/completions`.
Alternatively, open [Models and prices in the Zenith Telegram bot](https://t.me/zenith_service_bot),
tap the required model, and use its exact ID in Kilo.

```jsonc
{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "zenith/YOUR_MODEL_ID_FROM_GET_V1_MODELS",
  "provider": {
    "zenith": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "{env:ZENITH_API_KEY}",
        "baseURL": "https://api.zenithmarket.dev/v1"
      },
      "models": {
        "YOUR_MODEL_ID_FROM_GET_V1_MODELS": {
          "name": "Zenith model",
          "tool_call": true,
          "limit": {
            "context": 131072,
            "output": 16384
          }
        }
      }
    }
  }
}
```

Set `ZENITH_API_KEY` to the Zenith key before restarting VS Code, then select
`zenith/YOUR_MODEL_ID_FROM_GET_V1_MODELS`. Keep the key in global trusted
configuration or the user environment, not in a project config. Set each
model's context and output limits to its actual limits so Kilo can compact
context correctly.

## Minimal OpenAI-Compatible Request

```bash
curl https://api.zenithmarket.dev/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ZENITH_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "YOUR_MODEL_ID_FROM_GET_V1_MODELS",
    "messages": [
      { "role": "user", "content": "Reply exactly: ok" }
    ]
  }'
```

## Prompt Cache

Prompt-cache availability and TTL depend on the selected model and live route.
Keep the client default unless the current bot catalog or integration declares
cache support. `cache_control` and `zenith_cache: { "mode": "on" }` can request
caching; request `5m` or `1h` only when that TTL is explicitly available for
the route. Unsupported TTLs are rejected.

## GPT Image 2

GPT Image 2 is available through the OpenAI-compatible API when it is listed
by the current catalog. Use `POST /v1/images/generations` for generation and
`POST /v1/images/edits` for editing. The catalog controls availability and
prices for the 1K, 2K, and 4K request size tiers; check `GET /v1/models` before
sending a request and use only a listed tier.

## Errors, Security, And Billing

Read the response body for the actionable error. Fix `4xx` request, key, or
balance problems before retrying; retry temporary service failures later.
Do not expose Zenith keys in logs, source code, or client-side applications.
Public integrations must call only `https://api.zenithmarket.dev` and must not
send Zenith keys to upstream-provider or third-party domains.