§01

Start in three steps

Sign up with email or a Google account. Sign up free
Top up in the console, then create an API key.
Point your app's base URL to ours, paste your API key, and set model to a name from the models page. See models

§02

Endpoint & authentication

OpenAI format (most tools and SDKs) uses the address with /v1:

https://api.macloudai.com/v1

Anthropic format (Anthropic SDK, Claude Code) uses the address without /v1:

https://api.macloudai.com

Send the API key in the Authorization: Bearer sk-... header (Anthropic format also accepts x-api-key). The key is your balance: keep it out of frontend code and public repos.

§03

OpenAI SDK

from openai import OpenAI

client = OpenAI(base_url="https://api.macloudai.com/v1", api_key="sk-...")
r = client.chat.completions.create(
    model="gem-3.8-flash",
    messages=[{"role": "user", "content": "Halo"}],
)
print(r.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.macloudai.com/v1", apiKey: process.env.API_KEY });
const r = await client.chat.completions.create({
  model: "gem-3.8-flash",
  messages: [{ role: "user", content: "Halo" }],
});
console.log(r.choices[0].message.content);

curl https://api.macloudai.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gem-3.8-flash", "messages": [{"role": "user", "content": "Halo"}], "stream": true}'

Streaming is supported.

§04

Anthropic SDK

import anthropic

client = anthropic.Anthropic(base_url="https://api.macloudai.com", api_key="sk-...")
r = client.messages.create(
    model="hk-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Halo"}],
)
print(r.content[0].text)

The Anthropic-format address has no /v1.

§05

Claude Code

Set these variables in your terminal, then run claude (add them to ~/.zshrc or ~/.bashrc to keep them):

export ANTHROPIC_BASE_URL=https://api.macloudai.com
export ANTHROPIC_AUTH_TOKEN=sk-...
export ANTHROPIC_MODEL=hk-5-5
claude

§06

Cursor

Open Settings → Models.
Enter your key under OpenAI API Key, turn on Override OpenAI Base URL and enter https://api.macloudai.com/v1.
Click + Add model, enter a model name from the models page, then click Verify.

§07

Cherry Studio

Settings → Model Provider → Add, choose type OpenAI (Anthropic also works for Claude models).
Set API Host to https://api.macloudai.com and API Key to your key.
Click Manage or Add and enter a model name from the models page.

§08

LobeChat

In Settings → Language Model → OpenAI, enter your API key and API proxy address https://api.macloudai.com/v1. If you self-host, set these variables:

OPENAI_API_KEY=sk-...
OPENAI_PROXY_URL=https://api.macloudai.com/v1

§09

Billing & errors

Each call is deducted from your balance by input and output tokens; prices are on the models page. When the balance runs out, requests are refused and work again right after you top up.

Code	Meaning
401	The API key is wrong, disabled or deleted.
403	Not enough balance, or this key can't use that model.
404	Wrong model name. Use the exact name from the models page.
429	Too many requests. Wait a moment and try again.
5xx	The model is temporarily failing. Retry shortly.