Zrelay API documentation
Each Zrelay key is for one provider and uses that provider's request structure. Claude, GPT, and Grok share api.zrelay.net, but their headers, paths, and JSON payloads differ. Pick a provider below.
DeepSeek, Gemini, GLM and Kimi are also available on Base through POST /v1/chat/completions. Create a key for the matching provider in your account and use an exact model ID from the model list. When omitted, the output token budget defaults to 4,096. DeepSeek Pro is temporarily unavailable.
Your key, standard headers
The Zrelay key you receive starts with zr_live_ and is created for one provider. Use that provider's native request format; the required header depends on the wire format.
+ anthropic-version: 2023-06-01
One host, native paths
All traffic goes through api.zrelay.net. Zrelay selects an upstream route using the endpoint and model family while preserving compatible request formats. A key works only with the provider it was created for.
/v1/image/generations alias
Claude
Point any Anthropic SDK at Zrelay with the base URL below. The SDK appends /v1/messages for you. Application installation and configuration live in Setup.
Raw request
curl https://api.zrelay.net/v1/messages \ -H "x-api-key: zr_live_..." \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5", "max_tokens": 1024, "messages": [ {"role": "user", "content": "Explain Zrelay in one line."} ] }'
Python · Anthropic SDK
from anthropic import Anthropic client = Anthropic( base_url="https://api.zrelay.net", # no /v1 api_key="zr_live_...", ) msg = client.messages.create( model="claude-opus-5", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}], ) print(msg.content[0].text)
GPT
Use the OpenAI-compatible API with a base URL that includes /v1. GPT supports both responses and chat_completions. Codex installation and configuration live in Setup.
Chat Completions request
curl https://api.zrelay.net/v1/chat/completions \ -H "Authorization: Bearer zr_live_..." \ -H "content-type: application/json" \ -d '{ "model": "gpt-6-sol", "messages": [ {"role": "user", "content": "Explain Zrelay in one line."} ] }'
Responses API request
curl https://api.zrelay.net/v1/responses \ -H "Authorization: Bearer zr_live_..." \ -H "content-type: application/json" \ -d '{ "model": "gpt-5.6-terra", "input": "Refactor this function for readability." }'
Python · OpenAI SDK
from openai import OpenAI client = OpenAI( base_url="https://api.zrelay.net/v1", # include /v1 api_key="zr_live_...", ) resp = client.chat.completions.create( model="gpt-6-sol", messages=[{"role": "user", "content": "Hello"}], ) print(resp.choices[0].message.content)
Generate and edit images
Use a GPT provider key and either gpt-image-2.5-flare or gpt-image-2.5-sunburst. A successful generation or an accepted edit request costs $0.30 of ZRelay Base service credit. This is ZRelay's rate, not a verified provider price. Flare is suited to fast everyday work; Sunburst is suited to precise visual work. Compare image rates.
Use /v1/images/generations, the OpenAI SDK path also confirmed against the provider. Zrelay accepts /v1/image/generations as a compatibility alias and sends it to the plural route. Use prompt for the image description. This endpoint does not take Chat Completions messages or temperature.
Raw request
curl -sS https://api.zrelay.net/v1/images/generations \
-H "Authorization: Bearer zr_live_..." \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5-flare",
"prompt": "A watercolor illustration of a lighthouse at sunrise."
}' \
| jq -r '.data[0].b64_json' \
| base64 --decode > lighthouse.pngFor Sunburst, change only the model ID. The JSON response contains the image as base64 in data[0].b64_json; decode it to save the file. The OpenAI SDK calls the plural path automatically:
Python · OpenAI SDK
import base64
from openai import OpenAI
client = OpenAI(base_url="https://api.zrelay.net/v1", api_key="zr_live_...")
result = client.images.generate(
model="gpt-image-2.5-sunburst",
prompt="A watercolor illustration of a lighthouse at sunrise.",
)
with open("lighthouse.png", "wb") as image:
image.write(base64.b64decode(result.data[0].b64_json))Edit images
Use POST /v1/images/edits with multipart/form-data. Send one image, or repeat image[] for ordered reference images. The optional mask is one file. ZRelay accepts one output only: omit n or send n=1; streaming and partial images are not supported.
curl -sS https://api.zrelay.net/v1/images/edits \ -H "Authorization: Bearer zr_live_..." \ -F "model=gpt-image-2.5-sunburst" \ -F "image=@photo.png" \ -F 'prompt=Replace the background with a quiet beach at sunset' \ | jq -r '.data[0].b64_json' \ | base64 --decode > edited.png
curl -sS https://api.zrelay.net/v1/images/edits \ -H "Authorization: Bearer zr_live_..." \ -F "model=gpt-image-2.5-flare" \ -F "image[]=@product.png" \ -F "image[]=@style.png" \ -F "mask=@mask.png" \ -F 'prompt=Keep the product and apply the reference style only inside the masked area' \ | jq -r '.data[0].b64_json' \ | base64 --decode > edited.png
The official API permits up to 16 reference images. OpenAI documents masks as matching the image format and dimensions and carrying an alpha channel; ZRelay does not inspect pixel dimensions, actual encoding, or alpha and leaves those checks to the provider. ZRelay enforces a 32 MiB limit on the complete multipart request, including all images, mask and fields. The provider's documented 50 MB mask/image limit is therefore not the effective ZRelay limit.
Supported options are background, input_fidelity, moderation, output_compression, output_format, quality, size and user. Chat parameters, URLs, file IDs, Files API uploads and Responses API image tools are outside this route. The provider behind ZRelay has not been verified with a real edit request; local tests use mocks and verify forwarding only.
Existing GPT Chat and Responses routes accept image inputs for supported multimodal models. Use their normal request format when you want the model to read an image; use the generation or edit endpoint when you want an image returned.
Grok
Grok exposes only the OpenAI-compatible Chat Completions format. Set the base URL with /v1 and select chat_completions as the backend.
Raw request
curl https://api.zrelay.net/v1/chat/completions \ -H "Authorization: Bearer zr_live_..." \ -H "content-type: application/json" \ -d '{ "model": "grok-4.6", "messages": [ {"role": "user", "content": "What just happened in the world?"} ] }'
Python · OpenAI SDK (Grok)
from openai import OpenAI client = OpenAI( base_url="https://api.zrelay.net/v1", # include /v1 api_key="zr_live_...", ) resp = client.chat.completions.create( model="grok-4.6", messages=[{"role": "user", "content": "Hello"}], ) print(resp.choices[0].message.content)
Check your balance
Authenticate with a paid Zrelay key to read your shared account balance, settled spend, pending reservations and usage by model. Per-key spending quotas are managed separately in the account portal.
# your key must be exported first (see the Setup guide) curl -s https://api.zrelay.net/v1/usage \ -H "x-api-key: $ZRELAY_API_KEY" | python3 -m json.tool
No python3? Drop the pipe and it prints raw JSON.
The paid-key response includes name, quota_usd (total Zrelay service credit granted), balance_usd (unconsumed service credit), spent_usd, pending_usd and remaining_usd (spendable after reservations). spent_last_24h_usd and requests_last_24h cover a rolling 24-hour window. by_model reports requests, input/output/reasoning tokens and cost; by_day reports daily spend. This endpoint reports account totals, not the individual key’s spending cap.
Ready to build?
Install the native CLI tools against your key, or jump straight to pricing and pick a tier.