Beginner15 min11 節

PingAI Quickstart: Create a Key, First Request, SDKs, and Claude Code

Start by creating an account and an API key, send your first request with curl, then connect to PingAI with the OpenAI / Anthropic SDKs and Claude Code, and finally check usage in the Console.

1. What Is Ping…2. Prerequisite…3. Create Your …4. First Reques…5. Integrate wi…6. Integrate wi…7. Integrate wi…8. Connect Clau…9. One-Click Se…10. Check Usage …11. Common Error…

1What Is PingAI: A Multi-Model AI API Gateway

PingAI is an AI API gateway based in Hong Kong. It serves the full Claude model line through one OpenAI / Anthropic-compatible endpoint, so you do not sign up with each upstream or juggle different SDKs. The core design is transparent routing: it does not rewrite your request body, treats upstreams as black boxes, and owns only two metrics — stability (multi-upstream failover, circuit breakers, ordered degradation) and cost (routing scores, weighted round-robin).

As a developer you only need:

One pk--prefixed API key (created in the Console)
A base URL: https://api.pingai.hk/v1 for OpenAI-compatible, https://api.pingai.hk for Anthropic-compatible
A model ID such as claude-sonnet-5

The next sections walk you from zero to your first successful call.

Read source

2Prerequisites: Register, Get a Plan, and Open the Console

Before you start you need:

A PingAI account (register and sign in)
Either a credits subscription (1 credit = HK$1, deducted per request based on model price) or a pay-as-you-go top-up
Access to the Console (Dashboard) — this is where you create keys, check usage, and manage billing

Subscription plans come in tiers that include a monthly credits quota; pay-as-you-go simply deducts from your prepaid balance. Which mode you pick depends on your usage — see the pricing page for details.

Read source

3Create Your First API Key

Create a key on the Console → Keys page:

1Click "Create Key"
2Enter a name, e.g. "Production" or "Personal dev"
3The full key in pk-xxxxx format is shown only once — copy and save it immediately

The key can use "subscription quota" (counts against your plan credits) or "pay-as-you-go" (deducts from balance), and you can set a budget cap.

Security notes:

An API key is as valuable as money — it is full access to your account
Store it in environment variables or a secret manager; never commit it to frontends, public repos, or chat logs
If it leaks, revoke and recreate it in the Console immediately

Read source

4First Request with curl (OpenAI-Compatible)

PingAI provides the OpenAI-compatible endpoint /v1/chat/completions with Authorization: Bearer pk-xxx. Replace $PINGAI_API_KEY with your key:

bash

curl https://api.pingai.hk/v1/chat/completions \
  -H "Authorization: Bearer $PINGAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"Introduce Hong Kong in one sentence"}]}'

Windows PowerShell:

powershell

curl.exe https://api.pingai.hk/v1/chat/completions `
  -H "Authorization: Bearer $env:PINGAI_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"Introduce Hong Kong in one sentence"}]}'

In the JSON response, choices[0].message.content is the model reply and usage shows prompt / completion tokens.

Read source

5Integrate with the Python OpenAI SDK

Because the endpoint is OpenAI-compatible, use the official openai SDK and just change base_url and api_key:

bash

pip install openai

python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.pingai.hk/v1",
    api_key="pk-xxx",
)

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Introduce Hong Kong in one sentence"}],
)
print(response.choices[0].message.content)

Better: keep the key in an environment variable:

python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.pingai.hk/v1",
    api_key=os.getenv("PINGAI_API_KEY"),
)

Read source

6Integrate with the Node.js OpenAI SDK

In Node.js use the official openai npm package, changing baseURL and apiKey:

bash

npm install openai

import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://api.pingai.hk/v1',
  apiKey: process.env.PINGAI_API_KEY,
})

const response = await client.chat.completions.create({
  model: 'claude-sonnet-5',
  messages: [{ role: 'user', content: 'Introduce Hong Kong in one sentence' }],
})
console.log(response.choices[0].message.content)

If you already use any OpenAI-compatible SDK or framework, just swap the base URL and key — no business logic changes needed.

Read source

7Integrate with the Anthropic Protocol: /v1/messages

When you need the native Anthropic protocol (e.g. Claude Code or the Anthropic SDK), use the /v1/messages endpoint with a bare-domain base URL and authenticate with x-api-key (or Authorization: Bearer):

bash

curl https://api.pingai.hk/v1/messages \
  -H "x-api-key: $PINGAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1024,"messages":[{"role":"user","content":"Introduce Hong Kong in one sentence"}]}'

Python with the official anthropic SDK:

bash

pip install anthropic

python

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.pingai.hk",
    api_key="pk-xxx",
)

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Introduce Hong Kong in one sentence"}],
)
print(response.content[0].text)

Read source

8Connect Claude Code: Change One Base URL

Claude Code can point at a third-party gateway through environment variables. Point it at PingAI and authenticate with a pk- key — no official Claude subscription required.

Option 1: write the env block in ~/.claude/settings.json (applies globally):

json

{
  "env": {
    "ANTHROPIC_API_KEY": "pk-xxx",
    "ANTHROPIC_BASE_URL": "https://api.pingai.hk"
  }
}

Option 2: export in the shell (current terminal only):

bash

export ANTHROPIC_API_KEY=pk-xxx
export ANTHROPIC_BASE_URL=https://api.pingai.hk

PowerShell:

powershell

$env:ANTHROPIC_API_KEY = "pk-xxx"
$env:ANTHROPIC_BASE_URL = "https://api.pingai.hk"

Run claude in your project directory and type /status — if it shows the PingAI base URL and an auth token, the connection is live.

Read source

9One-Click Setup with pingai-cli (Claude Desktop / Claude Code / Cursor)

Prefer not to write config by hand? The official PingAI CLI offers a full setup wizard:

bash

# No install needed, run directly
npx pingai wizard

Or install globally:

bash

npm install -g pingai-cli
pingai wizard

Wizard flow:

1System check (OS, RAM, disk, Node.js)
2Software selection — Claude Desktop / Claude Code / Cursor
3Install guidance (for software not detected)
4Gateway configuration — writes the API key and gateway URL automatically
5Connectivity test — verifies the configuration works

Other commands: pingai doctor checks your machine, pingai configure reconfigures, pingai status shows current config, pingai uninstall removes it.

Read source

10Check Usage and Balance in the Console

After you are connected, review real usage in the Console:

Usage page: request count, total spend (HK$), average daily requests / spend, switchable between "last 7 / 30 / 90 days", with CSV export
By-model breakdown: see which models consume the most requests, useful for tuning your model strategy
Dashboard overview: remaining credits / balance, plan quota progress
Keys page: each key's billing mode and budget at a glance

Checking usage regularly is the first step to controlling cost (see the "Usage Management & Cost Optimization" course).

Read source

11Common Errors and Troubleshooting

HTTP 401: API key wrong, expired, or revoked — check the pk- key, or recreate it in the Console
HTTP 429: RPM rate limit or quota exceeded — wait and retry, or check whether plan credits are exhausted
HTTP 404 / 400: model ID does not exist — confirm you used a valid model (e.g. claude-sonnet-5)
Connection refused: base URL typo, or VPN / firewall blocking api.pingai.hk — check the domain and network
Empty or malformed reply: confirm you are using POST and the correct Content-Type
max_tokens too small: the reply gets truncated — raise the limit

Always start troubleshooting with a raw curl call to the endpoint — it quickly tells you whether the problem is the key, the model, or the network.

Read source

Want to see more?

Tutorials are free — watch with a PingAI account

8Connect Claude Code: Change One Base URL

Claude Code can point at a third-party gateway through environment variables. Point it at PingAI and authenticate with a pk- key — no official Claude subscription required.

Option 1: write the env block in ~/.claude/settings.json (applies globally):

json

{
  "env": {
    "ANTHROPIC_API_KEY": "pk-xxx",
    "ANTHROPIC_BASE_URL": "https://api.pingai.hk"
  }
}

Option 2: export in the shell (current terminal only):

bash

export ANTHROPIC_API_KEY=pk-xxx
export ANTHROPIC_BASE_URL=https://api.pingai.hk

PowerShell:

powershell

$env:ANTHROPIC_API_KEY = "pk-xxx"
$env:ANTHROPIC_BASE_URL = "https://api.pingai.hk"

Run claude in your project directory and type /status — if it shows the PingAI base URL and an auth token, the connection is live.

Read source