Connect your application to LaoZhang API

Send requests to one of the hosts below with your LaoZhang API key. OpenAI SDKs use https://api.laozhang.ai/v1; the Google Gen AI and Anthropic SDKs use the host root and add their own paths.

Domain	Use it when
`api.laozhang.ai`	By default; every example on this site uses it
`api-vip.laozhang.ai`	Your servers are in Europe or North America and you want a direct connection
`api2.laozhang.ai`	`api.laozhang.ai` can’t be reached from your network

All three domains accept the same API key, paths, and parameters, so switching changes only the hostname. The console opens on each of them too. Pick the request format your application already uses, then choose a model that your API key’s group can call.

Get an API key

Create an API key in Token management; the console calls it a token. When you create it, you choose its group and billing mode. The group decides which models the key can call. For the billing mode, choose Usage first (按量优先, recommended): a key in this mode can call both the usage-based text models and the per-call image model used below. Billing, token groups, and invoices explains both settings. Set the key as an environment variable in the terminal where you will run the examples:

export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"

Replace the placeholder with your key. Keep the key on your server and out of browser bundles, source control, and logs. Account-management AccessTokens are separate credentials, used only for account endpoints such as the balance query API. The examples use these models:

gpt-5.4-mini for text
gemini-3.8-flash for native Gemini requests
glm-5.2 for Anthropic Messages
gpt-image-2-vip for images

To use another model, copy its exact ID from Models and pricing and check that your key’s group can call it. For help choosing a text model and request format, see the Text generation API guide.

Send a text request

Chat Completions takes a messages array. Send your API key as a Bearer token, with a JSON body:

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1/chat/completions" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "Reply only with: connected"}]
  }'

The answer is in choices[0].message.content; for this prompt, expect connected. Replace the message content with your own prompt to use the same request in your application. The OpenAI protocol reference covers message fields, streaming, and model-specific options.

OpenAI SDK

The OpenAI SDK builds the endpoint path, so set its base URL to https://api.laozhang.ai/v1 without adding /chat/completions.

Python
Node.js

Install the SDK:

python -m pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Reply only with: connected"}],
)
print(response.choices[0].message.content)

Install the SDK with npm install openai, then save this code in an .mjs file and run it with Node.js:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LAOZHANG_API_KEY,
  baseURL: "https://api.laozhang.ai/v1",
  timeout: 120_000,
  maxRetries: 0,
});
const response = await client.chat.completions.create({
  model: "gpt-5.4-mini",
  messages: [{ role: "user", content: "Reply only with: connected" }],
});
console.log(response.choices[0].message.content);

These examples turn off the SDK’s automatic retries so that your application decides when to repeat a request. The same client also reaches the Responses, Images, Audio, Embeddings, and Moderations endpoints. Use OpenAI models with LaoZhang API shows which endpoint each OpenAI model uses, including o3-pro, GPT Image, and the speech models.

Move an existing OpenAI app

An application that already uses the OpenAI SDK needs three changes: the API key and base URL in the client, shown below, and the model value in each request. The rest of your request code stays the same.

 client = OpenAI(
-    api_key=os.environ["OPENAI_API_KEY"],
+    api_key=os.environ["LAOZHANG_API_KEY"],
+    base_url="https://api.laozhang.ai/v1",
 )

If your application configures the SDK only through environment variables, you can switch without changing code. The OpenAI Python and Node.js SDKs read OPENAI_API_KEY and OPENAI_BASE_URL:

export OPENAI_API_KEY="$LAOZHANG_API_KEY"
export OPENAI_BASE_URL="https://api.laozhang.ai/v1"

Before you send production traffic, check these points:

Model IDs. A model name that works with OpenAI may have a different ID or group on LaoZhang API. Copy exact IDs from Models and pricing; the OpenAI models guide lists the other differences from calling OpenAI directly.
Optional parameters. Sampling controls, output limits, structured output, and tool settings vary by model. Start with the required fields, then add the options your application uses. If a request returns an unsupported-parameter error, remove or adjust the field it names.
Retries. Keep retry logic in one place. If both the SDK and your application retry, one user action can produce several API calls.
Results. Run the minimal request above, then find it in call logs and confirm the model, token usage, and charge.

To switch back, restore the previous API key and base URL.

Responses API

The Responses API takes input in the request and returns an output array. Its request body differs from Chat Completions, so an application that switches must update both the request and the response parser.

cURL
Python

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1/responses" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "Reply only with: connected"
  }'

Use the same openai package installed above:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.responses.create(
    model="gpt-5.4-mini",
    input="Reply only with: connected",
)
print(response.output_text)

In raw JSON, collect the text values from content items of type output_text inside the output array. The SDK’s output_text helper does this for you. Other output items can contain reasoning or tool calls, so the first item is not necessarily the text answer. LaoZhang API supports OpenAI’s Responses API, so OpenAI text models such as GPT-6, GPT-5.6, GPT-5.4, and o3-pro can use it. Before you move a model from another vendor to this endpoint, send a minimal request to confirm it works. Server-side conversation state, previous_response_id, and built-in tools also depend on the model; if your application needs conversation history, keep the messages that your next request requires. The OpenAI Responses reference defines the upstream fields, and the Data Policy covers data handling.

Generate or edit an image

Both Images endpoints return a data array. Depending on the model, each item holds the image as Base64 in b64_json or as a download link in url. The examples use gpt-image-2-vip, which is billed per call while the text examples are usage-based. A key set to Usage first can call both; if an image request is rejected, check that the key’s billing mode is Usage first or Per-call (按次计费).

Generate an image

Send a JSON prompt to the generation endpoint:

curl --fail-with-body --max-time 360 \
  "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-vip",
    "prompt": "A blue ceramic cup on a white table, soft natural light, product photography."
  }' \
  -o generation.json

Edit an image

Place a reference image named input.png in your current directory, then upload it with your instructions as multipart form data:

curl --fail-with-body --max-time 360 \
  "https://api.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=gpt-image-2-vip" \
  -F "image[]=@input.png" \
  -F 'prompt=Change the background to pale blue. Keep the subject unchanged.' \
  -o edit.json

The @ syntax uploads the file contents. Let cURL set the multipart content type and boundary; do not add Content-Type: application/json to this request.

Save the result

The response file is JSON, not an image. Save this script as save_images.py; it uses only the Python standard library:

import base64
import json
import re
import sys
import urllib.request
from pathlib import Path

source = Path(sys.argv[1])
response = json.loads(source.read_text())
items = response.get("data") or []
if not items:
    sys.exit(f"No image in {source}: {response}")

for index, item in enumerate(items, start=1):
    if item.get("b64_json"):
        encoded = re.sub(r"^data:[^,]*,", "", item["b64_json"].strip())
        raw = base64.b64decode(encoded + "=" * (-len(encoded) % 4))
    elif item.get("url"):
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            raw = download.read()
    else:
        continue
    if raw.startswith(b"\x89PNG"):
        extension = "png"
    elif raw.startswith(b"\xff\xd8"):
        extension = "jpg"
    elif raw[:4] == b"RIFF" and raw[8:12] == b"WEBP":
        extension = "webp"
    else:
        extension = "bin"
    output = source.with_name(f"{source.stem}-{index}.{extension}")
    output.write_bytes(raw)
    print(f"Saved {output}")

Run it on either response file:

python save_images.py generation.json
python save_images.py edit.json

The script saves every image in data, for example generation-1.png. It handles:

Base64 that starts with a data:image/...;base64, prefix or lacks trailing = padding.
url results, which it downloads without your API key. Save URL results promptly and keep your own copy.

The Images API reference has Python SDK examples for both operations. Image sizes, quality settings, and output formats depend on the model; use the matching model guide when you add them.

Call Gemini with its native API

Gemini’s native API uses contents[].parts[] rather than OpenAI messages:

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Reply only with: connected"}]
    }]
  }'

Read the text parts in candidates[].content.parts[]. If no text is present, inspect finishReason and promptFeedback. For the Google Gen AI SDK, use the host root https://api.laozhang.ai with api_version="v1beta". The SDK adds the model path and API key header. The Gemini protocol reference includes a complete Python example, both authentication header options, and instructions for image, PDF, and audio input. To analyze the frames and audio of an MP4 video, see the Video understanding API.

Call the Anthropic Messages API

Applications built on the Anthropic Messages format, including the Anthropic SDKs, send requests to /v1/messages:

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1/messages" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "glm-5.2",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Reply only with: connected"}]
  }'

Required fields: model, messages, and max_tokens.
System prompt: put it in the top-level system field rather than in messages.
Response: the content array can hold text, thinking, and tool_use blocks.
Answer text: read the blocks whose type is text instead of assuming that the first block is the answer.

Claude models are temporarily offline due to limited capacity. We will post an announcement when they return. The Messages endpoint keeps working for the models marked Anthropic Messages in Models and pricing:

glm-5.2, available in the default and claude_code token groups, closely matches the behavior of Anthropic’s own Messages API.
deepseek-v4-pro and deepseek-v4-flash are also marked for this endpoint.

For the Anthropic Python SDK, pass base_url="https://api.laozhang.ai" and your LaoZhang API key; the SDK adds /v1/messages. The Claude protocol reference covers the SDK, streaming, and tool use.

More API operations

Models API: discover model IDs for your application.
Embeddings: turn text into vectors.
Audio transcription: upload audio and receive a transcript.
Moderation: submit content for classification.

Resolve common errors

Status	What to check
400	JSON syntax, field types, model options, and input length.
401	The API key, authentication header, and key expiration.
403	Token group, model permissions, and account restrictions.
404	The final URL and exact model ID; look for a duplicated `/v1`.
429	The error body for rate, concurrency, capacity, or balance limits.
5xx or timeout	Network conditions, model availability, and call logs.

Correct invalid requests before retrying. For temporary failures, use bounded backoff and avoid stacking SDK retries on top of application retries. A client timeout does not cancel generation or show whether a charge occurred. Check call logs before you resubmit an image request. For support, email hi@laozhang.ai or message @laozhang_cn on Telegram with the request time, model, endpoint, token group, and redacted error. Billing and refunds follow the Terms.

Use these docs in an AI coding tool

Give your coding assistant the target model, the task, and one of these files:

skill.md: connection rules and minimal requests for coding assistants, in English.
llms.txt and llms-full.txt: a page index and a full-text export of the documentation. Both currently cover the Chinese documentation.

Supply credentials through the environment instead of pasting them into prompts.

API references

LaoZhang API references:

Upstream references define request fields and model capabilities. Model IDs, access, and prices on LaoZhang API are listed in Models and pricing and the console.

OpenAI: API reference, Chat Completions, Responses, and models
Anthropic: Messages API
Google: Gemini API documentation and generateContent reference

For Alibaba Cloud, ByteDance, xAI, Black Forest Labs, DeepSeek, and other vendors, see official API docs by vendor, which also maps each vendor to its LaoZhang API guide.

Get started

Image Generation & Editing APIs

Video Generation APIs

Text APIs

Multimodal & Audio APIs

Connect your application to LaoZhang API

Get an API key

Send a text request

OpenAI SDK

Move an existing OpenAI app

Responses API

Generate or edit an image

Generate an image

Edit an image

Save the result

Call Gemini with its native API

Call the Anthropic Messages API

More API operations

Resolve common errors

Use these docs in an AI coding tool

API references

​Get an API key

​Send a text request

​OpenAI SDK

​Move an existing OpenAI app

​Responses API

​Generate or edit an image

​Generate an image

​Edit an image

​Save the result

​Call Gemini with its native API

​Call the Anthropic Messages API

​More API operations

​Resolve common errors

​Use these docs in an AI coding tool

​API references

Get an API key

Send a text request

OpenAI SDK

Move an existing OpenAI app

Responses API

Generate or edit an image

Generate an image

Edit an image

Save the result

Call Gemini with its native API

Call the Anthropic Messages API

More API operations

Resolve common errors

Use these docs in an AI coding tool

API references