Zukko API — Full Knowledge Base

Generated from https://zukko.pro/docs — upload to an AI or Save as PDF via Print.

# Zukko API — Full Knowledge Base

> This file is the full Zukko API documentation. Upload it to an AI (ChatGPT, Claude, Cursor, etc.) so the assistant knows endpoints, auth, models, and examples.

Website: https://zukko.pro
API: https://api.zukko.pro
OpenAI-compatible base: https://api.zukko.pro/v1
Anthropic-compatible base: https://api.zukko.pro
Auth: Authorization: Bearer fetch_YOUR_KEY

---

# Introduction

# Introduction

Zukko provides a single API for Claude, GPT, and other models. You use one `fetch_*` key and send every request to one domain:

```bash
https://api.zukko.pro
```

## What Zukko is

Zukko works as an AI gateway: you connect one endpoint and then access Claude, GPT, and other models through a single layer for auth, usage, and billing.

## What you get

- one API for multiple providers;
- unified dashboard and billing;
- compatibility with OpenAI-like and Anthropic-like SDKs;
- quick setup in IDEs, agents, and your own apps.

## Base URLs

```bash
OpenAI-compatible:    https://api.zukko.pro/v1
Anthropic-compatible: https://api.zukko.pro
```

## Typical setup

In most cases the integration looks like this:

1. create an API key in the Zukko dashboard;
2. use your `fetch_*` key in the app;
3. change the base URL to `https://api.zukko.pro` or `https://api.zukko.pro/v1`;
4. pick a model and send a request.

## Next steps

1. Register on Zukko.
2. Create an API key with the `fetch_` prefix.
3. Open Quick Start and configure your SDK or IDE.
4. Pick a model and send your first request.

---

# For beginners

The simplest walkthrough: what Zukko is, where to send requests, and how not to get lost.

## In one sentence

Zukko is a single “outlet” for AI. You connect `api.zukko.pro` once with a `fetch_...` key, then call Claude, GPT, and other models as if they were one provider.

## Three things to know

1. **API key** — a secret like `fetch_xxxxx` from the dashboard → API keys. Never share it.
2. **API host** — `https://api.zukko.pro`. That is Zukko’s server, not Anthropic/OpenAI directly.
3. **Model** — a string like `claude-sonnet-5` or `gpt-4o` in the request `model` field.

## Which URL to use

| Tool | Base URL |
| --- | --- |
| Cursor / OpenAI SDK / most IDEs | `https://api.zukko.pro/v1` |
| Claude Code / Anthropic SDK | `https://api.zukko.pro` |

Both hit the same Zukko gateway. Only the request shape differs (OpenAI-style vs Anthropic-style).

## First request without pain

1. Sign up at [zukko.pro](https://zukko.pro).
2. Top up balance (otherwise requests fail).
3. Create a `fetch_...` key.
4. Paste the key and base URL into your IDE or curl.
5. Send a short prompt — if you get a reply, you’re good.

Minimal curl (Anthropic-style):

```bash
curl https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer fetch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-5","max_tokens":256,"messages":[{"role":"user","content":"Hello"}]}'
```

## Common mistakes

- **401 / unauthorized** — bad or missing key. Check `Bearer fetch_...`.
- **402 / insufficient funds** — top up in the dashboard.
- **404 / model not found** — typo in the model name. See the models list in the docs.
- **Still pointing at the provider URL** — the IDE must use `api.zukko.pro`, not `api.anthropic.com` or `api.openai.com`.

## Download API for AI

This is a **knowledge base** for the full Zukko API: URLs, keys, models, request examples, integrations.

Download one file and drop it into ChatGPT, Claude, Cursor, or any other AI — it will know the full API and can write code / configs correctly.

**MD** — best for AIs (recommended). TXT, DOC, and PDF are also available.

Next: [Quick Start](/docs/introduction/quick-start) or your IDE guide in the left menu.

---

# Quick Start

You can connect Zukko in a few minutes. Here is the minimum setup to send your first request.

## Step 1. Create an API key

Create a key in the Zukko dashboard with the `fetch_` prefix.

```bash
fetch_xxxxxxxxxxxxxxxxxxxxx
```

## Step 2. Set the base URL

For OpenAI-compatible clients use:

```bash
https://api.zukko.pro/v1
```

For Anthropic-compatible clients use:

```bash
https://api.zukko.pro
```

## Step 3. Send your first request

```bash
curl https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer fetch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-5","max_tokens":256,"messages":[{"role":"user","content":"Hi"}]}'
```

## Step 4. Connect your IDE or SDK

Once the test works, you can connect Cursor, Claude Code, VS Code, Codex, or your own scripts through OpenAI / Anthropic SDKs.

---

# API Reference

# Authentication

All requests to Zukko API use a `fetch_*` key.

## Authorization header

```bash
Authorization: Bearer fetch_YOUR_KEY
```

## Basic rules

- use HTTPS: `https://api.zukko.pro`;
- never pass the key in the query string;
- for Anthropic-compatible requests add `anthropic-version`;
- the same key works across all compatible endpoints.

## Example

```bash
curl https://api.zukko.pro/v1/models \
  -H "Authorization: Bearer fetch_YOUR_KEY"
```

---

# POST /v1/chat/completions

OpenAI-compatible endpoint for chat and text generation.

## When to use

Use this endpoint if your SDK or app expects the OpenAI Chat Completions format.

## Request example

```bash
curl https://api.zukko.pro/v1/chat/completions \
  -H "Authorization: Bearer fetch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-terra","messages":[{"role":"user","content":"Hello"}]}'
```

## What to send

- `model` — model id;
- `messages` — array of messages;
- `stream` — optional, if you need streaming.

---

# POST /v1/images/generations

OpenAI-compatible endpoint for image generation and editing (Nano Banana, GPT Image, and more).

## When to use

Use this endpoint for text-to-image, edit, and reference-to-image models. Text models still go through `/v1/chat/completions` or `/v1/messages`.

## Request example

```bash
curl https://api.zukko.pro/v1/images/generations \
  -H "Authorization: Bearer fetch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai-gpt-image-2-text-to-image",
    "prompt": "A cinematic travel poster for Kyoto in autumn",
    "size": "1024x1024",
    "quality": "high"
  }'
```

## What to send

- `model` — image model id;
- `prompt` — text description;
- `images` — array of URLs or data URLs (for edit / reference);
- `size`, `quality` — optional for GPT Image.

---

# POST /v1/messages

Anthropic-compatible endpoint for Claude-style requests.

## When to use

Use this endpoint if your client expects the Anthropic Messages API format.

## Request example

```bash
curl https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer fetch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-5","max_tokens":256,"messages":[{"role":"user","content":"Hi"}]}'
```

## What to send

- `model` — model id;
- `messages` — message array;
- `max_tokens` — generation limit.

---

# POST /v1/messages/count_tokens

Token counting for Anthropic-compatible payloads before sending the main request.

## Request example

```bash
curl https://api.zukko.pro/v1/messages/count_tokens \
  -H "Authorization: Bearer fetch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"Count these tokens"}]}'
```

---

# GET /v1/models

Returns the list of available models.

## Request example

```bash
curl https://api.zukko.pro/v1/models \
  -H "Authorization: Bearer fetch_YOUR_KEY"
```

## When to use

- to load the model catalog;
- to populate model selectors in UI;
- to integrate with IDEs and agents.

---

# GET /v1/models/info

Returns extended model information: description, provider, pricing, and extra capabilities.

## Request example

```bash
curl https://api.zukko.pro/v1/models/info \
  -H "Authorization: Bearer fetch_YOUR_KEY"
```

---

# GET /v1/balance

Returns the current account balance.

## Request example

```bash
curl https://api.zukko.pro/v1/balance \
  -H "Authorization: Bearer fetch_YOUR_KEY"
```

---

# GET /v1/usage

Returns usage statistics for the account or API key.

## Request example

```bash
curl https://api.zukko.pro/v1/usage \
  -H "Authorization: Bearer fetch_YOUR_KEY"
```

---

# POST /v1/responses

Responses-style endpoint for a unified generation flow.

## Request example

```bash
curl https://api.zukko.pro/v1/responses \
  -H "Authorization: Bearer fetch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-terra","input":"Write a short hello world example"}'
```

---

# POST /v1/web-search

Endpoint for requests with web search, when this capability is enabled by the service.

## Request example

```bash
curl https://api.zukko.pro/v1/web-search \
  -H "Authorization: Bearer fetch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"latest Anthropic model release"}'
```

---

# GET /health

Operational endpoint for checking service availability.

## Request example

```bash
curl https://api.zukko.pro/health
```

## When to use

- in monitoring;
- for readiness / liveness checks;
- before proxying external traffic.

---

# IDE Integrations

# Choose provider

Pick the type in the IDE first, then URL and `fetch_...` key.

| Want | Provider | Base URL |
| --- | --- | --- |
| Claude | **Anthropic** | `https://api.zukko.pro` |
| OpenAI API / Compatible | **OpenAI** | `https://api.zukko.pro/v1` |

Same key for both — [API Keys](/app/api-keys).

---

# Cursor IDE

1. Provider: **OpenAI Compatible**
2. Base URL: `https://api.zukko.pro/v1`
3. API Key: `fetch_...`

Needs paid Cursor Pro (trial won't work).

## Aliases

| Alias | Model |
| --- | --- |
| `cursor47` | claude-opus-4.7 |
| `cursor46` | claude-opus-4.6 |
| `cursor45` | claude-opus-4.5 |
| `cursor46s` | claude-sonnet-5 |
| `cursor45s` | claude-sonnet-4.5 |
| `cursorgpt54` | gpt-5.6-terra |
| `cursorgpt55` | gpt-5.6-sol |
| `cursorgemini` | gemini-3.1-pro-preview |

---

# Claude Code

Official Anthropic coding agent (CLI + VS Code extension). Prefer the Russian guide on this page for the full walkthrough.

Provider: **Anthropic**. Base URL without `/v1`. See [Choose provider](/docs/ide-integrations/choose-provider).

## Required values

- `ANTHROPIC_BASE_URL` = `https://api.zukko.pro` (no `/v1` suffix)
- `ANTHROPIC_AUTH_TOKEN` = your `fetch_...` key from [API Keys](/app/api-keys)

## Permanent setup (~/.claude/settings.json)

```json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.zukko.pro",
    "ANTHROPIC_AUTH_TOKEN": "fetch_...",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4.8",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-5",
    "DISABLE_TELEMETRY": "1",
    "DISABLE_ERROR_REPORTING": "1"
  }
}
```

Then run `claude`. Use `ANTHROPIC_AUTH_TOKEN`, not `ANTHROPIC_API_KEY`.

---

# OpenCode

| Provider | Base URL | Key |
| --- | --- | --- |
| **Anthropic** | `https://api.zukko.pro` | `fetch_...` |

```json
{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.zukko.pro",
        "apiKey": "fetch_..."
      }
    }
  }
}
```

---

# VS Code Extensions

Provider first, then URL and `fetch_...`.

| Extension | Provider | Base URL |
| --- | --- | --- |
| Cline | OpenAI Compatible | `https://api.zukko.pro/v1` |
| Roo Code | Anthropic | `https://api.zukko.pro` |
| Kilo Code | OpenAI Compatible | `https://api.zukko.pro/v1` |

---

# Codex

Provider: **OpenAI**. Base URL: `https://api.zukko.pro/v1`. Key: `fetch_...`.

```toml
model = "gpt-5.6-terra"
model_provider = "zukko"

[model_providers.zukko]
name = "zukko"
base_url = "https://api.zukko.pro/v1"
wire_api = "responses"
requires_openai_auth = true
```

Key in `~/.codex/auth.json`: `OPENAI_API_KEY`.

---

# Agents

# Hermes

[Hermes Agent](https://hermes-agent.nousresearch.com/) → Zukko. Key: `fetch_...`.

Exit chat, then `hermes model`. Pick one:

- Anthropic — Claude models via API key or Claude Code
- OpenAI ▸ — Codex CLI or direct OpenAI API

| Option | Next | Base URL | Key |
| --- | --- | --- | --- |
| Anthropic | API key (not Claude Code OAuth) | `https://api.zukko.pro` | `fetch_...` |
| OpenAI | direct OpenAI API | `https://api.zukko.pro/v1` | `fetch_...` |

## Anthropic

```yaml
model:
  provider: anthropic
  default: claude-sonnet-5
  base_url: https://api.zukko.pro
```

`ANTHROPIC_API_KEY=fetch_...` in `~/.hermes/.env`.

## OpenAI

```bash
OPENAI_API_KEY=fetch_...
OPENAI_BASE_URL=https://api.zukko.pro/v1
```

## If it fails

- **401** — check `fetch_...` key
- **402** — top up balance
- **404 on Anthropic** — `base_url` must not include `/v1`
- **Wrong OpenAI host** — use `https://api.zukko.pro/v1` with `openai-api`

---

# OpenClaw

[OpenClaw](https://docs.openclaw.ai/) → Zukko custom provider. Config: `~/.openclaw/openclaw.json`. Key: `fetch_...`.

Need both `models.providers` and `agents.defaults.models` allowlist.

| Option | api | baseUrl |
| --- | --- | --- |
| OpenAI Compatible | `openai-completions` | `https://api.zukko.pro/v1` |
| Anthropic Messages | `anthropic-messages` | `https://api.zukko.pro` |

```json5
{
  models: {
    mode: "merge",
    providers: {
      zukko: {
        baseUrl: "https://api.zukko.pro/v1",
        apiKey: "fetch_...",
        api: "openai-completions",
        models: [{ id: "claude-sonnet-5", name: "Claude Sonnet 4.6", contextWindow: 200000, maxTokens: 8192 }],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "zukko/claude-sonnet-5" },
      models: { "zukko/claude-sonnet-5": { alias: "sonnet" } },
    },
  },
}
```

For Anthropic Messages: same file, `api: "anthropic-messages"`, `baseUrl: "https://api.zukko.pro"` (no `/v1`).

## If it fails

- **model not allowed** — add allowlist `zukko/<id>`
- **Missing in /models** — check provider and allowlist
- **401** — key and URL from the table

---

_End of Zukko API knowledge base. Source: https://zukko.pro/docs_