---
name: laozhang-api
description: Integrate or troubleshoot LaoZhang API using its API keys, SDK base URLs, OpenAI-compatible endpoints, or Gemini and Claude native protocols. Use when the user has chosen laozhang.ai, not for direct provider accounts or unrelated AI services.
metadata:
  homepage: "https://www.laozhang.ai"
  docs: "https://docs.laozhang.ai"
  api_key_env: "LAOZHANG_API_KEY"
---

## Connect to LaoZhang API

Use `https://api2.laozhang.ai` for API requests and the console. The product
website is `https://www.laozhang.ai`; documentation is at
`https://docs.laozhang.ai`. Respond in the user's language. English documentation
uses the `/en/` prefix.

Start with the user's task, model, and client library. Read the relevant
endpoint reference before adding optional parameters. Choose exact model IDs
and check token-group access in the [console](https://api2.laozhang.ai/account/pricing).
A model listing helps discover IDs but does not establish support for every
endpoint or parameter.

Read the model API key from `LAOZHANG_API_KEY` in an authorized server-side
environment. If it is absent, ask for a secure local credential source.
Never print it, commit it, or request it in chat. Model API keys differ from
account management AccessTokens; use the credential required by the endpoint.

## Configure the SDK base URL

| Client | Base URL |
| --- | --- |
| OpenAI SDK | `https://api2.laozhang.ai/v1` |
| Google Gen AI SDK | `https://api2.laozhang.ai` with `api_version="v1beta"` |
| Anthropic SDK | `https://api2.laozhang.ai` |

Let the SDK append its endpoint path. Do not duplicate version prefixes.
Gemini native requests use the AI Studio format, not Vertex project, location,
and publisher paths. OpenAI-compatible calls use `Authorization: Bearer`.
Gemini native calls accept Bearer or `x-goog-api-key`; the Google SDK supplies
the latter. See the Claude reference for its version and authentication headers.

## Generate text

Install `openai`, then configure the client:

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api2.laozhang.ai/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(response.choices[0].message.content)
```

Replace the example model with one available to the user's token group.
Chat Completions uses `messages` and returns `choices`. Responses uses
`client.responses.create(model=..., input=...)`; read `response.output_text`
for text or inspect typed items in `output` for tools and other content.
Do not assume server-side conversation state across requests.

## Generate or edit images

For an OpenAI Images model, use `POST /v1/images/generations` with a JSON
body containing `model` and `prompt`. With the configured OpenAI client:

```python
image_client = client.with_options(timeout=360.0)
result = image_client.images.generate(
    model="gpt-image-2-vip",
    prompt="A blue ceramic cup on a wooden table.",
)
```

To edit a local image, use `POST /v1/images/edits` and upload it as multipart:

```python
with open("input.png", "rb") as source:
    result = image_client.images.edit(
        model="gpt-image-2-vip",
        image=[source],
        prompt="Change the background to pale blue. Keep the cup unchanged.",
    )
```

For image requests, increase the client timeout to suit the workload; the
[Images reference](https://docs.laozhang.ai/en/api-reference/images) uses 360
seconds. With cURL, upload files using `-F 'image[]=@input.png'` and let cURL
set the multipart boundary. Do not set `Content-Type: application/json` for
file uploads.

Read `data[].b64_json` or the model's supported URL output. Decode or download
the image bytes before saving them. Inspect the format, dimensions, and the
requested visual change. Never rename the JSON response as an image or send
the API key to an image download URL. Consult the model guide for quality,
size, masks, transparency, and multiple-image options; DALL·E parameters do
not apply universally to GPT Image.

## Use Gemini's native API

Install `google-genai`. Configure the host root and API version:

```python
import os
from google import genai

client = genai.Client(
    api_key=os.environ["LAOZHANG_API_KEY"],
    http_options={
        "base_url": "https://api2.laozhang.ai",
        "api_version": "v1beta",
        "timeout": 120_000,
    },
)
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Say hello in one sentence.",
)
print(response.text)
```

REST requests use `contents` and return `candidates`. Inspect all content
parts, finish reasons, and prompt feedback when handling more than text.
Keep complete model content, including any thought signatures, when carrying
history into a follow-up request. REST field names such as `inlineData` differ
from Python SDK properties such as `inline_data`.

## Diagnose a failed request

- **400:** correct the body, field types, or unsupported parameters before retrying.
- **401/403:** check the API key, authentication header, token group, and permissions.
- **404:** check the constructed URL, model ID, and endpoint access.
- **503:** read the error; an unavailable channel in the selected group may require a model or group change.
- **429:** distinguish balance problems from temporary rate or capacity limits.
- **Timeout/5xx:** inspect call logs before repeating a generation request. A timeout does not establish cancellation or zero cost.

Keep retries bounded and avoid enabling them independently in both the SDK
and application. Use [call logs](https://api2.laozhang.ai/log) to reconcile
requests and [current pricing](https://api2.laozhang.ai/account/pricing) for
cost estimates. The [Terms](https://www.laozhang.ai/terms) govern billing and
refunds; the [Data Policy](https://www.laozhang.ai/data-policy) governs data handling.

## Find the right reference

- [API integration guide](https://docs.laozhang.ai/en/api-manual)
- [Chat Completions](https://docs.laozhang.ai/en/api-reference/chat-completions)
- [Images: generation and editing](https://docs.laozhang.ai/en/api-reference/images)
- [Gemini native API](https://docs.laozhang.ai/en/api-reference/gemini)
- [Claude native API](https://docs.laozhang.ai/en/api-reference/claude)
- [Token management](https://api2.laozhang.ai/token)
- [Documentation index](https://docs.laozhang.ai/llms.txt)
- [Full documentation](https://docs.laozhang.ai/llms-full.txt)

Use the index to find a relevant page before loading the full export. Append
`.md` to a documentation page URL to read its Markdown version.