EtherGate developer docs
Follow the production path: create a workspace, add credits, create a cr_ API key, choose a Chinese model, call it through an OpenAI-compatible SDK, then inspect usage and billing.
1. Workspace
Use a workspace to separate API keys, credits, members and usage reports for each project.
2. API key
Generate an API key from the console and store it as ETHERGATE_API_KEY.
3. First request
Use https://ethergate.cn/v1 as the compatible API base URL.
From signup to first production request
This is the shortest path a developer should follow before sending real traffic.
1. Create workspace
Use a workspace to separate API keys, credits, members and usage reports for each project.
2. Add credits
Top up the workspace before calling upstream models. The gateway checks balance before routing.
3. Create key
Generate an API key from the console and store it as ETHERGATE_API_KEY.
4. Pick model
Send requests to IDs like deepseek/deepseek-chat or qwen/qwen-plus.
5. Send request
Point the OpenAI SDK at EtherGate, pass Authorization: Bearer cr_..., and use a supported model ID.
6. Inspect usage
Use Usage and Keys pages to review requests, tokens, errors, model mix and credit spend.
OpenAI-compatible API reference
EtherGate normalizes model calls through a small set of stable gateway endpoints.
Base URL
Use the gateway base URL in SDKs and HTTP clients. Do not call upstream providers directly from user apps.
| Endpoint | Purpose |
|---|---|
| POST /v1/chat/completions | Create a chat completion using any supported EtherGate model ID. |
| GET /v1/models | List model IDs and metadata exposed by the gateway. |
| GET /healthz | Lightweight liveness check for deployment and load balancers. |
| GET /status | Operational status for gateway, providers and configured models. |
Request fields
The chat completion request follows the OpenAI shape with EtherGate model IDs.
| Parameter | Status | Notes |
|---|---|---|
| model | Required | Use a model ID from the catalog, for example qwen/qwen-plus. |
| messages | Required | Array of system, user, assistant and tool messages. |
| stream | Optional | Set true to receive incremental chunks over a streaming response. |
| temperature | Optional | Optional sampling control. Leave unset for provider defaults. |
| max_tokens | Optional | Optional completion token cap when the upstream provider supports it. |
| tools | Optional | Optional tool definitions for models that support function/tool calling. |
Model IDs
Use these slugs in the model field. The catalog page shows pricing, context and provider readiness.
Benchmark methodology
Model detail benchmarks combine configured provider telemetry, routed traffic, pricing tiers and static model metadata. Treat them as routing signals, not vendor-certified scores.
Traffic and routing signals
Weekly tokens, route health and provider mix come from the catalog and gateway status when available.
Provider performance signals
Latency, throughput and uptime charts are comparative snapshots for configured routes and should be verified with your own payloads.
Pricing signals
Input, output and cache prices are current route estimates; production billing is based on actual gateway ledger entries.
OpenAI SDK
Keep your existing client and switch the base URL.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.ETHERGATE_API_KEY,
baseURL: "https://ethergate.cn/v1",
});
const completion = await client.chat.completions.create({
model: "qwen/qwen-plus",
messages: [
{ role: "system", content: "You are a concise launch assistant." },
{ role: "user", content: "Write an onboarding email for developers." }
],
stream: false,
});
console.log(completion.choices[0]?.message?.content);import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ETHERGATE_API_KEY"],
base_url="https://ethergate.cn/v1",
)
completion = client.chat.completions.create(
model="deepseek/deepseek-v4-flash",
messages=[
{"role": "user", "content": "Write a concise launch checklist"}
],
)
print(completion.choices[0].message.content)curl https://ethergate.cn/v1/chat/completions \
-H "Authorization: Bearer $ETHERGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Request-Id: demo-001" \
-d '{
"model": "deepseek/deepseek-v4-flash",
"messages": [
{ "role": "user", "content": "Write a launch checklist" }
],
"stream": false
}'QClaw, OpenClaw and Hermes integrations
Use the same EtherGate key and OpenAI-compatible base URL in agent tools. The tool selects the route model; EtherGate handles provider routing.
Copy to tools
Copy the native command for your OS and run it in a system terminal, not inside an already-running Hermes/OpenClaw session. Add --home or -Home when the tool uses a non-standard config directory.
Run this in a system terminal. Rerun it to rotate the key or refresh models; existing EtherGate config is replaced, other config is preserved. If QClaw uses a custom config directory, add --home or -Home.
Do not paste this command into an already-running Hermes or OpenClaw prompt. Restart the tool after installation; then you can ask the installed EtherGate Skill to refresh models in natural language.
Multiple installs or a non-standard config directory? Add --home or -Home and point it to the real tool home.
curl -fsSL 'https://ethergate.cn/console/skills/ethergate-provider/install.sh' | bash -s -- --target qclaw --api-key '<your-ethergate-key>' --locale 'en'Streaming
Streaming keeps the OpenAI SDK shape: set stream true and iterate over chunks.
const stream = await client.chat.completions.create({
model: "qwen/qwen-plus",
messages: [{ role: "user", content: "Draft a product changelog" }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}Credits, usage and billing
Credits belong to the workspace. Requests are attributed to the API key and visible in usage reports.
Credits fund requests
The gateway checks workspace balance before routing. Add credits before production traffic.
Debits follow token usage
Successful upstream requests create ledger entries with model, provider, token and request metadata.
Usage is inspectable
Use Usage for workspace totals and Keys for per-key request, token, error and model mix data.
Failed requests are traceable
Errors include request IDs and provider context so support can connect customer reports to gateway logs.
Provider keys
User keys and upstream provider keys are separate. Users receive only cr_ keys; Qwen, DeepSeek and Moonshot keys stay on the Go gateway.
User-facing keys
Developers create cr_ keys in the console. These keys identify the workspace, control billing and are sent in customer requests.
Gateway provider keys
Provider keys are platform-owned server secrets on the Go gateway. Configure them in gateway environment variables and never expose them through NEXT_PUBLIC_* variables or browser code.
ETHERGATE_DEEPSEEK_API_KEY=YOUR_DEEPSEEK_KEY
ETHERGATE_QWEN_API_KEY=YOUR_QWEN_KEY
ETHERGATE_MOONSHOT_API_KEY=YOUR_MOONSHOT_KEYResponse headers
Use these values to connect support, logs and customer-facing diagnostics.
| Header | Use |
|---|---|
| X-Request-Id | Stable request identifier. Send your own or let the gateway generate one. |
| X-EtherGate-Provider | Upstream provider selected for the request, such as deepseek, qwen or moonshot. |
| X-RateLimit-Limit | Current per-key request limit for the active one-minute window. |
| X-RateLimit-Remaining | Requests left in the current rate-limit window. |
| Retry-After | Seconds to wait before retrying after a 429 response. |
Common errors
The gateway returns OpenAI-style JSON error bodies with EtherGate-specific codes.
401 invalid_api_key
The Authorization bearer token is missing, revoked or unknown.
402 insufficient_credits
The account balance is empty. Add credits before sending more requests.
429 rate_limit_exceeded
The API key exceeded its per-minute request limit. Respect Retry-After.
502 provider_request_failed
The selected upstream provider failed or is temporarily unavailable.
Error body
Errors use an OpenAI-style JSON envelope so existing clients can handle them predictably.
{
"error": {
"message": "The Authorization bearer token is missing, revoked or unknown.",
"type": "authentication_error",
"code": "invalid_api_key"
}
}Before going live
Run this checklist before sharing the API base URL with external users.