> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 老张API 开发文档：OpenAI、Claude 与 Gemini 接入

> 配置老张API密钥与 Base URL，用 OpenAI、Anthropic Messages 和 Gemini 协议发送第一个请求，生成、编辑并保存图片，迁移已有 OpenAI 应用。

用老张API密钥和下表中的域名，即可通过 OpenAI、Anthropic Messages 或 Gemini 协议发送文本和图片请求；各 SDK 的 Base URL 见[配置请求地址](#配置请求地址)。

| 域名 | 适用情况 |
| - | - |
| `api.laozhang.ai` | 默认域名，本站示例统一使用 |
| `api-vip.laozhang.ai` | 服务器在欧美，需要直连 |
| `api2.laozhang.ai` | `api.laozhang.ai` 无法访问时使用 |

三个域名使用同一个 API Key，接口路径和请求参数都相同，切换时只改域名；控制台也可以通过这三个域名打开。

## 准备密钥与模型

1. 在[令牌管理](https://api.laozhang.ai/token)创建 API Key，并为它选择令牌分组和计费模式。计费模式选择按量优先（推荐），同一个密钥就能调用下文按量计费的文本模型和按次计费的 `gpt-image-2-vip`；含义见[计费说明](/pricing#令牌计费模式)。
2. 在[模型与价格总表](/models)或控制台[模型与价格](https://api.laozhang.ai/account/pricing)页面复制完整模型 ID，确认该模型可以在令牌所属的分组调用。
3. 将密钥配置为服务端环境变量：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
```

下文分别使用 `gpt-5.4-mini`、`gemini-3.8-flash`、`glm-5.2` 和 `gpt-image-2-vip`。更换模型时复制完整模型 ID，并确认它支持所用的接口；文本模型和协议怎么选，见[文本生成 API](/api-capabilities/text-generation)。

调用模型使用 API Key，查询余额等账户管理接口使用系统令牌 AccessToken，两者不能互换；余额查询见[余额查询 API](/api-capabilities/balance-query)。密钥不要放进浏览器代码或提交到 Git 仓库。

## 配置请求地址

OpenAI SDK 使用以下 Base URL，由 SDK 拼接 Chat Completions、Responses 或 Images 的路径：

```text theme={null}
https://api.laozhang.ai/v1
```

Google Gen AI SDK 与 Anthropic SDK 使用域名根路径：

```text theme={null}
https://api.laozhang.ai
```

SDK 会在域名后拼接各协议的路径：

* Gemini 原生请求：`/v1beta/models/模型ID:generateContent`，Gemini SDK 需指定 API 版本 `v1beta`
* Anthropic Messages 请求：`/v1/messages`

不要在域名后同时添加 `/v1` 和 `/v1beta`。

## OpenAI 协议

GPT-5.6、`o3-pro`、GPT Image、音频、向量和审核等 OpenAI 模型分别使用哪个端点，见 [OpenAI 模型接入](/api-reference/openai)。

### Chat Completions

向 `POST /v1/chat/completions` 发送 `messages` 数组，文本回复位于 `choices[0].message.content`。下面的请求要求模型只返回“连接成功”。

```bash theme={null}
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": "请只回复：连接成功"}]
  }'
```

消息角色、可选参数和响应字段见 [Chat Completions 参考](/api-reference/chat-completions)。

### OpenAI SDK

Python 安装 `python -m pip install openai`；Node.js 安装 `npm install openai`，并将代码保存为 `.mjs` 文件。两种示例都读取前面设置的 `LAOZHANG_API_KEY`。

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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": "请只回复：连接成功"}],
    )
    print(response.choices[0].message.content)
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    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: "请只回复：连接成功" }],
    });
    console.log(response.choices[0].message.content);
    ```
  </Tab>
</Tabs>

示例关闭自动重试，由应用决定失败后是否重发。`temperature`、输出长度等可选字段按模型说明添加，不要将一个模型的默认值用于所有模型。

### 迁移已有 OpenAI 应用

已经使用 OpenAI SDK 的应用可以保留原来的方法调用，只替换三项配置：

1. **API Key**：换成老张API密钥；
2. **Base URL**：换成 `https://api.laozhang.ai/v1`，Python 的参数名是 `base_url`，Node.js 是 `baseURL`；
3. **模型 ID**：换成当前令牌分组可以调用的完整 ID，可在[模型与价格总表](/models)中查找。

应用只能通过环境变量配置时，OpenAI 官方 SDK 会读取 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`。Base URL 已经包含 `/v1`，自行拼接请求路径时不要再加一次，否则路径重复会返回 404。

切换后先发送只包含必需字段的请求，确认应用能读取文本或保存图片，再按目标模型的说明加入输出长度、采样、格式和工具等参数。模型能接受的参数和默认值各不相同，不要把一个模型的配置直接套用到所有模型。

模型 ID、令牌分组和计费与 OpenAI 官方直连的区别，见 [OpenAI 模型接入](/api-reference/openai#与-openai-官方直连的区别)；重试与超时的处理见[处理调用错误](#处理调用错误)。

### Responses API

向 `POST /v1/responses` 发送 `input`。它与 Chat Completions 的 `messages` 请求格式不同，适合使用 OpenAI Responses 客户端的应用。

老张API兼容 OpenAI 的 Responses API，GPT-6、GPT-5.6、GPT-5.4、`o3-pro` 等 OpenAI 文本模型都可以用它调用；换用 OpenAI 以外厂商的模型时，先用下面的最小请求确认。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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": "请只回复：连接成功"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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="请只回复：连接成功",
    )
    print(response.output_text)
    ```
  </Tab>
</Tabs>

Python SDK 的 `output_text` 聚合文本答案。处理原始 JSON 时按下面的顺序读取，不要固定把 `output[0]` 当作文本消息：

1. 遍历 `output[]`，找到类型为 `message` 的项目；
2. 在该项目的 `content[]` 中找到类型为 `output_text` 的项，读取其 `text`。

需要多轮对话时，在应用中保存历史，并在后续 `input` 中发送所需内容。`tools`、文件输入、`previous_response_id` 和 `store` 等字段有各自的模型与服务要求，不是切换到 Responses 后即可通用的功能。

字段定义见 [OpenAI Responses 参考](https://developers.openai.com/api/reference/resources/responses/methods/create)，数据处理约定见[数据政策](https://www.laozhang.ai/zh-cn/data-policy)。

### 生成图片

向 `POST /v1/images/generations` 发送模型和提示词，将响应保存为 `generation-response.json`：

```bash theme={null}
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": "一只蓝色陶瓷杯放在白色桌面上，柔和的自然光，简洁的产品摄影。"
  }' \
  -o generation-response.json
```

### 编辑图片

向 `POST /v1/images/edits` 上传参考图和修改指令。先将要编辑的图片放在当前目录，命名为 `input.png`：

```bash theme={null}
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=把背景改为浅蓝色，保留主体的外观和位置。" \
  -o edit-response.json
```

`-F` 会上传文件并自动设置 multipart 的 `Content-Type`，无需手动指定。

### 保存图片结果

生成与编辑的响应都在 `data[]` 中返回图片，每一项可能是 Base64 编码的 `b64_json`，也可能是图片地址 `url`。JSON 响应文件不能直接作为图片打开，需要先解码或下载。

将以下代码保存为 `save_images.py`。它只使用 Python 标准库，按实际图片格式决定扩展名，并能处理：

* 带或不带 `data:image/...;base64,` 前缀的 `b64_json`；
* 末尾缺少 `=` 填充的 Base64；
* `url` 结果。

```python theme={null}
import base64
import json
import sys
import urllib.request
from pathlib import Path

if len(sys.argv) != 3:
    raise SystemExit("用法：python save_images.py 响应文件.json 输出文件前缀")

payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
if payload.get("error"):
    raise SystemExit(f"请求失败：{payload['error']}")
items = payload.get("data") or []
if not items:
    raise SystemExit("响应中没有图片结果，请检查错误信息和调用日志")


def decode_base64(value):
    # 去掉可能出现的 data:image/...;base64, 前缀，并补齐缺失的 = 填充
    if value.startswith("data:"):
        value = value.split(",", 1)[1]
    value = "".join(value.split())
    return base64.b64decode(value + "=" * (-len(value) % 4))


def image_extension(raw):
    if raw.startswith(b"\x89PNG\r\n\x1a\n"):
        return "png"
    if raw.startswith(b"\xff\xd8\xff"):
        return "jpg"
    if raw[:4] == b"RIFF" and raw[8:12] == b"WEBP":
        return "webp"
    raise SystemExit("返回内容不是 PNG、JPEG 或 WebP 图片")


for index, item in enumerate(items, start=1):
    if item.get("b64_json"):
        raw = decode_base64(item["b64_json"])
    elif item.get("url"):
        # 下载图片地址时不需要附带老张API密钥
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            raw = download.read()
    else:
        raise SystemExit(f"第 {index} 项没有 b64_json 或 url")
    output = Path(f"{sys.argv[2]}-{index}.{image_extension(raw)}")
    output.write_bytes(raw)
    print(f"已保存 {output}")
```

生成请求结束后运行：

```bash theme={null}
python save_images.py generation-response.json generated
```

编辑请求结束后运行：

```bash theme={null}
python save_images.py edit-response.json edited
```

输出文件名类似 `generated-1.png`，扩展名由实际图片格式决定。响应中返回 `url` 时，拿到响应后尽快下载保存。

使用 OpenAI Python SDK 的生成、编辑示例见 [Images API 参考](/api-reference/images)。尺寸、质量和输出格式按具体模型设置，不要将 DALL·E 的 `quality="hd"` 或 `style` 参数直接用于 GPT Image。

### 其他接口

* [Models API](/api-reference/models)：获取模型 ID；实际调用权限以令牌分组为准。
* [文本向量](/api-capabilities/text-embedding)：通过 `POST /v1/embeddings` 获取向量。
* [音频转录](/api-capabilities/audio-transcription)：通过 `POST /v1/audio/transcriptions` 上传音频文件。
* [内容审核](/api-capabilities/moderation)：通过 `POST /v1/moderations` 提交待审核内容。

## Gemini 原生协议

Gemini 使用 `contents[].parts[]` 传入内容，在 `candidates[].content.parts[]` 返回结果。下面使用 `gemini-3.8-flash` 发送文本请求：

```bash theme={null}
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": "请只回复：连接成功"}]}]
  }'
```

也可以将 Bearer 认证头替换为 `x-goog-api-key: $LAOZHANG_API_KEY`，Google Gen AI SDK 使用后一种认证方式。SDK 安装、完整配置及响应解析见 [Gemini 原生协议参考](/api-reference/gemini)。

这里使用 AI Studio 风格的 `v1beta` 接口，不使用 Vertex AI 的 project/location/publisher 路径。

需要让 Gemini 分析 MP4 视频的画面和音轨时，见[视频理解 API](/api-capabilities/video-understanding)。

## Claude 协议（Anthropic Messages）

Anthropic Messages 格式的请求发送到 `POST /v1/messages`，要求如下：

* 请求头：`Authorization: Bearer`，并带上 `anthropic-version`
* 必填字段：`model`、`messages` 和 `max_tokens`

下面使用 `glm-5.2` 发送文本请求：

```bash theme={null}
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": "请只回复：连接成功"}]
  }'
```

回复位于 `content[]` 内容块中，与 Chat Completions 的 `choices` 不同。读取时注意：

* 按每一项的 `type` 读取，文本在 `type` 为 `text` 的项里；
* `content[]` 中还可能有 `thinking`、`tool_use` 等其他类型的项，不要固定读取 `content[0]`；
* 系统提示放在请求顶层的 `system` 字段。

Claude 模型自 2026 年 9 月 24 日起未在老张API上架，上架时会在[网站公告](/changelog)通知。Messages 协议仍可正常使用，请求和响应与 Anthropic 官方 Messages 接口基本一致：

* `glm-5.2`：在 `default` 和 `claude_code` 分组都可以调用；
* `deepseek-v4-pro` 和 `deepseek-v4-flash`：价格配置中同样标注了 Anthropic Messages 端点。

使用 Anthropic SDK 时，Base URL 设为 `https://api.laozhang.ai`，完整配置见 [Claude 协议参考](/api-reference/claude)。

## 处理调用错误

| 状态或现象 | 优先检查 |
| - | - |
| 400 | JSON 格式、参数类型、模型限制与上下文长度 |
| 401 | API Key、认证头，以及环境变量是否在当前进程中生效 |
| 403 / 模型不可用 | 令牌分组、模型权限和账号限制 |
| 404 | 接口路径与模型 ID，尤其是重复的 `/v1` |
| 429 | 错误正文中的限流、余额或容量信息 |
| 5xx / 超时 | 网络、服务状态和调用日志 |

遇到 400 时，先移除新增的可选参数，再根据错误正文修正请求。

请求成功但应用没有显示结果时，检查解析方式是否与接口一致：

* Chat Completions 读取 `choices`
* Responses 读取 `output`
* Images 读取 `data`
* Anthropic Messages 读取 `content`

参数或权限错误需要修正后再发起请求。临时限流可采用有限次数的退避重试；图片等耗时请求超时后，先查看[调用日志](https://api.laozhang.ai/log)，再决定是否重新提交。

客户端断开不表示服务端已取消，SDK 和业务层同时重试也可能增加请求次数。

若仍无法定位，把请求时间、模型 ID、接口路径和完整错误信息发给支持团队（[hi@laozhang.ai](mailto:hi@laozhang.ai)），不要附上 API Key。权限问题见[模型可用性说明](/faq/model-availability)，服务及退款条款见[用户协议](https://www.laozhang.ai/zh-cn/terms)。

## 让编程助手读取文档

将以下链接提供给 AI 开发工具，再说明目标模型和需要完成的任务。API Key 仍通过本地环境变量配置。

* [skill.md 接入说明](https://docs.laozhang.ai/skill.md)：接入步骤、协议与配置要求。
* [llms.txt 文档索引](https://docs.laozhang.ai/llms.txt)：按任务查找相关文档。
* [llms-full.txt 文档全文](https://docs.laozhang.ai/llms-full.txt)：需要完整资料时读取。

## 协议参考

以下是上游厂商的官方文档，用于查阅字段定义和模型能力。其中的 Base URL、密钥获取方式和价格不适用于老张API。

通过老张API调用时，仍使用本页的 Base URL 和老张API密钥，可调用的模型以[模型与价格总表](/models)为准。

* **OpenAI**：[Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)、[Responses](https://developers.openai.com/api/reference/resources/responses/methods/create)、[图片生成与编辑](https://developers.openai.com/api/docs/guides/image-generation)、[模型目录](https://developers.openai.com/api/docs/models)
* **Anthropic**：[Messages API](https://platform.claude.com/docs/zh-CN/api/messages)
* **Google**：[Gemini API 文档](https://ai.google.dev/gemini-api/docs)、[generateContent 参考](https://ai.google.dev/api/generate-content)、[Gen AI Python SDK](https://googleapis.github.io/python-genai/)

阿里云百炼、火山方舟、xAI、Black Forest Labs、DeepSeek 等其他厂商的官方文档，以及它们对应的老张API页面，见[资源导航](/resources)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.