Help Center

From sign-up and creating a key to connecting Claude Code and SDKs — setup guides, troubleshooting and FAQs in one place.

menu_book

Full Documentation Site

More in-depth integration guides, model notes and best practices on our dedicated docs site.

Visit Docs Sitearrow_forward

Base URL

https://your-domain.com

OpenAI Auth

Authorization: Bearer sk-xxx

Anthropic Auth

x-api-key: sk-xxx

Quick Start

Get started with Zivv API in 4 steps.

Sign up and add balance

Create a Zivv account and add a small balance to test models and cost on a real task.

Create an API key and choose a group

Open the API Keys page and create an sk- key. For Claude Code choose the "Claude MAX" group; otherwise pick a group with the models you need.

Set the Base URL

Claude Code and the Anthropic SDK use the root domain (no /v1). OpenAI SDKs, Codex, Cursor and other OpenAI-compatible tools use the /v1 address.

Start calling

Keep your existing code and just swap the Base URL and API key. Every request and its cost shows up on the console Usage page.

Anthropic protocol (Claude Code)	https://your-domain.com
OpenAI-compatible protocol	https://your-domain.com/v1

Connect Claude Code

Claude Code is our core use case. After creating a key in the Claude MAX group, pick the setup that matches your system.

export ANTHROPIC_BASE_URL=https://your-domain.com
export ANTHROPIC_AUTH_TOKEN=sk-your-key
claude

Things to check

check_circleANTHROPIC_BASE_URL is the root domain only — do not add /v1.
check_circlePut your key in ANTHROPIC_AUTH_TOKEN, then reopen the terminal before running claude.
check_circleIf you previously signed in to an official account and see an auth conflict warning, run /logout in Claude Code first.
check_circleRun /status in Claude Code to confirm the API address points to Zivv.
check_circleThe API Keys page in the console can import the config into CC Switch in one click.

Learn about the Claude MAX grouparrow_forward

Groups

Each key belongs to one group, which sets the available models, billing ratio and upstream route.

Claude MAX group

Built for Claude Code: our proprietary pool of official Claude Max subscriptions, connected directly to Anthropic, with no rate limits.

infoNative Anthropic protocol only (/v1/messages) — use it with Claude Code or the Anthropic SDK.

Other groups

Cover GPT, Gemini and more, split by model and ratio — for OpenAI-compatible tools, SDKs and desktop clients.

infoSee Model Hub for the models and ratio of each group.

Open Model Hubarrow_forward

Billing

Pay as you go — you are charged only for what you use.

calculate

Formula

Cost = tokens × official model price × group ratio. Input and output are counted separately; streaming and non-streaming are billed the same.

currency_exchange

Settled at ¥1 = $1

Your RMB balance converts 1:1 to USD prices, so there is no live exchange rate to worry about.

savings

No monthly fee

No monthly fee, minimum spend or hidden charges. Balance never expires.

bar_chart

Itemized usage

The console Usage page shows tokens and cost for every request, by key, model and time.

Full billing rulesopen_in_new

Troubleshooting

Find the cause by status code — most setup problems are solved here.

Code	Meaning	What to do
401	Invalid key	Check the key was copied in full with no extra spaces and has not been deleted. Your login password is not an API key.
402	Insufficient balance	Top up in the console and check whether the key itself has a spending limit. Team keys draw from the team owner's balance.
403	Not allowed	The key's group does not include this model, or the protocol does not match (for example, using the Claude MAX group in an OpenAI-compatible client). Switch to a matching group or client.
404	Wrong address or model	OpenAI-compatible tools need /v1; Claude Code does not. Copy model names from Model Hub.
429	Temporarily limited	Lower concurrency and retry shortly. If it persists, check the status page or contact support.
5xx	Upstream busy or failing	Usually recovers on its own within moments — retry. If it persists, check the status page.

FAQ

Do I need a separate key for each model?expand_more

No. One key can call every model in its group. If you use Claude Code and GPT-based tools, separate keys make usage easier to tell apart.

I can sign in on the website, so why does my tool return 401?expand_more

Website login and API keys are different credentials. Tools need the sk- key from the API Keys page, not your account password.

Can I switch models inside Claude Code?expand_more

Yes. Use /model in Claude Code to switch between Opus, Sonnet and Haiku; you are billed for the model actually used.

How do I confirm requests go through Zivv?expand_more

After a call, check the console Usage page. If you see a record with the right time, model and cost, you are connected.

What if my key leaks?expand_more

Delete it on the API Keys page right away and create a new one. Never put keys in public repositories, screenshots or front-end code.

Can a team share one balance?expand_more

Yes. Create a team and hand out keys to members; all spend comes from the team owner's balance, with team and per-member budgets.

API Reference

Endpoints, code samples, client setup and request parameters.

API Endpoints

Zivv API supports the OpenAI, Anthropic and Gemini protocol formats.

Method	Endpoint	Description
POST	/v1/chat/completions	Chat Completions (OpenAI format, streaming supported)
POST	/v1/messages	Messages (Anthropic format, streaming supported)
POST	/v1/responses	Responses (OpenAI Responses API, for Codex CLI)
POST	/v1/images/generations	Image Generation (supports streaming SSE output)
POST	/v1/gemini/{model}:{method}	Gemini native protocol passthrough (generateContent / streamGenerateContent)
GET	/v1/models	List available models

Code Examples

Drop-in replacement — just change your base URL.

curl https://your-domain.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Client Setup Guides

Setup steps for popular AI tools and SDKs. For Claude Code, see "Connect Claude Code" above.

Save the following to ~/.codex/config.toml and put your key in the ZIVV_API_KEY environment variable. The API Keys page in the console can generate the full script for you.

~/.codex/config.toml

model_provider = "zivv"
model = "gpt-5.5"

[model_providers.zivv]
name = "zivv"
base_url = "https://your-domain.com/v1"
env_key = "ZIVV_API_KEY"
wire_api = "responses"

Request Parameters

Supported parameters by protocol. Select a protocol to see its parameters.

Parameter	Type	Required	Description
model	string	Yes	Model ID, e.g. claude-sonnet-5
messages	array	Yes	Array of message objects with role and content
stream	boolean	No	Enable streaming output, default false
temperature	number	No	Sampling temperature, 0-2
top_p	number	No	Nucleus sampling parameter
max_tokens	number	No	Maximum output tokens
max_completion_tokens	number	No	Alternative to max_tokens, same behavior
tools	array	No	Function tool definitions for tool use
tool_choice	string\|object	No	Tool selection strategy: auto / required / none / specific tool

Image Generation

Use the Images API with gpt-image-2 to generate images, with streaming SSE support.

💡 Recommended: enable stream mode. Image generation typically takes 30-120 seconds; streaming avoids Cloudflare / gateway timeouts.

📝 For image editing (modifying existing images), use the Responses API (/v1/responses) with text models like gpt-5.5 and the image_generation tool.

Code Examples

curl https://your-domain.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cute cat wearing sunglasses on a beach",
    "stream": true,
    "size": "1024x1024",
    "quality": "high"
  }'

SSE Streaming Response Format

With stream enabled, the server returns generation progress and the final image (base64) via SSE chunks.

SSE Events

event: progress
data: {"type":"progress","progress":25}

event: progress
data: {"type":"progress","progress":50}

event: progress
data: {"type":"progress","progress":75}

event: result
data: {"type":"result","index":0,"b64_json":"iVBORw0KGgo..."}

event: done
data: [DONE]

Responses API

The OpenAI Responses API (/v1/responses) is the native interface for newer models like gpt-5.5, supporting vision and image generation.

💡 For gpt-5.5 with images, use the Responses API. Image type is input_image, and image_url is a plain string — no object wrapper needed.

📝 Use tools: [{type: "image_generation"}] to let text models generate images, including image editing (modifying existing images).

Vision & Image Generation

The Responses API supports both image input (vision) and image generation (via the image_generation tool).

# Vision: send image to gpt-5.5
curl https://your-domain.com/v1/responses \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "What is in this image?" },
          { "type": "input_image", "image_url": "https://example.com/photo.jpg" }
        ]
      }
    ]
  }'

# Image generation via Responses API
curl https://your-domain.com/v1/responses \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Generate an image of a sunset over mountains",
    "tools": [{ "type": "image_generation" }]
  }'

chat/completions vs responses

	chat/completions	responses
Request field	messages	input
Image type	image_url	input_image
Image URL format	{url: "..."}	"..."
Image generation	❌	image_generation tool
Response structure	choices[].message	output[]
Multi-turn	❌	previous_response_id

Still stuck?

support_agentOpen a ticket forumCommunity & contact monitoringService status

Ready to get started?

Create an account and get your API Key in seconds.