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:

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

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):

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.

fetch_xxxxxxxxxxxxxxxxxxxxx

Step 2. Set the base URL

For OpenAI-compatible clients use:

https://api.zukko.pro/v1

For Anthropic-compatible clients use:

https://api.zukko.pro

Step 3. Send your first request

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

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

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

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

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

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

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

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

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

----------

GET /v1/balance

Returns the current account balance.

Request example

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

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

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

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

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)

{
  "$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_...

{
  "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_....

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

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

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

OpenAI

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

{
  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_