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

请求发往下表任一域名，各 SDK 的 Base URL 写法见配置请求地址。

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

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

准备密钥与模型

在令牌管理创建 API Key，并为它选择令牌分组和计费模式。计费模式选择按量优先（推荐），同一个密钥就能调用下文按量计费的文本模型和按次计费的 GPT Image 2.5 VIP 模型；含义见计费说明。
在模型与价格总表复制完整模型 ID，确认该模型可以在令牌所属的分组调用。
将密钥配置为服务端环境变量：

export LAOZHANG_API_KEY="替换为你的老张API密钥"

下文使用的模型：

文本：gpt-5.4-mini（OpenAI 协议）、gemini-3.8-flash（Gemini 原生）、glm-5.2（Anthropic Messages）
图片：gpt-image-2.5-flare-vip 生成，gpt-image-2.5-sunburst-vip 编辑

更换模型时复制完整模型 ID，并确认它支持所用的接口；文本模型和协议怎么选，见文本生成 API。调用模型使用 API Key，查询余额等账户管理接口使用系统令牌 AccessToken，两者不能互换；余额查询见余额查询 API。密钥不要放进浏览器代码或提交到 Git 仓库。

配置请求地址

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

https://api.laozhang.ai/v1

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

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 模型接入。

Chat Completions

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

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 参考。

OpenAI SDK

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

Python
Node.js

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)

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);

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

迁移已有 OpenAI 应用

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

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

应用只能通过环境变量配置时，OpenAI 官方 SDK 会读取 OPENAI_API_KEY 和 OPENAI_BASE_URL。Base URL 已经包含 /v1，自行拼接请求路径时不要再加一次，否则路径重复会返回 404。切换后先发送只包含必需字段的请求，确认应用能读取文本或保存图片，再按目标模型的说明加入输出长度、采样、格式和工具等参数。模型能接受的参数和默认值各不相同，不要把一个模型的配置直接套用到所有模型。模型 ID、令牌分组和计费与 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 以外厂商的模型时，先用下面的最小请求确认。

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": "请只回复：连接成功"
  }'

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)

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

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

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

生成图片

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

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

编辑图片

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

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.5-sunburst-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 结果。

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}")

生成请求结束后运行：

python save_images.py generation-response.json generated

编辑请求结束后运行：

python save_images.py edit-response.json edited

输出文件名类似 generated-1.png，扩展名由实际图片格式决定。响应中返回 url 时，拿到响应后尽快下载保存。使用 OpenAI Python SDK 的生成、编辑示例见 Images API 参考。尺寸、质量和输出格式按具体模型设置，不要将 DALL·E 的 quality="hd" 或 style 参数直接用于 GPT Image。

其他接口

Models API：获取模型 ID；实际调用权限以令牌分组为准。
文本向量：通过 POST /v1/embeddings 获取向量。
音频转录：通过 POST /v1/audio/transcriptions 上传音频文件。

Gemini 原生协议

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

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 原生协议参考。这里使用 AI Studio 风格的 v1beta 接口，不使用 Vertex AI 的 project/location/publisher 路径。需要让 Gemini 分析 MP4 视频的画面和音轨时，见视频理解 API。

Claude 协议（Anthropic Messages）

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

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

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

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 字段。

Messages 协议的请求和响应与 Anthropic 官方 Messages 接口基本一致，可用的模型包括：

Claude 模型：2026 年 10 月 18 日重新上架，例如 claude-sonnet-5-5、claude-opus-5-5，与官方接口的差异见 Claude 模型的使用限制；
glm-5.2：在 default 和 claude_code 分组都可以调用；
deepseek-v4-pro 和 deepseek-v4-flash：价格配置中同样标注了 Anthropic Messages 端点。

使用 Anthropic SDK 时，Base URL 设为 https://api.laozhang.ai，完整配置见 Claude 协议参考。

处理调用错误

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

遇到 400 时，先移除新增的可选参数，再根据错误正文修正请求。请求成功但应用没有显示结果时，检查解析方式是否与接口一致：

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

参数或权限错误需要修正后再发起请求。临时限流可采用有限次数的退避重试；图片等耗时请求超时后，先查看调用日志，再决定是否重新提交。客户端断开不表示服务端已取消，SDK 和业务层同时重试也可能增加请求次数。若仍无法定位，把请求时间、模型 ID、接口路径和完整错误信息发给支持团队（hi@laozhang.ai），不要附上 API Key。权限问题见模型可用性说明，服务及退款条款见用户协议。

让编程助手读取文档

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

skill.md 接入说明：接入步骤、协议与配置要求。
llms.txt 文档索引：按任务查找相关文档。
llms-full.txt 文档全文：需要完整资料时读取。

协议参考

以下是上游厂商的官方文档，用于查阅字段定义和模型能力。其中的 Base URL、密钥获取方式和价格不适用于老张API。通过老张API调用时，仍使用本页的 Base URL 和老张API密钥，可调用的模型以模型与价格总表为准。

OpenAI：Chat Completions、Responses、图片生成与编辑、模型目录
Anthropic：Messages API
Google：Gemini API 文档、generateContent 参考、Gen AI Python SDK

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

开始使用

图像生成与编辑 API

视频生成 API

文本 API

多模态与音频 API

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

准备密钥与模型

配置请求地址

OpenAI 协议

Chat Completions

OpenAI SDK

迁移已有 OpenAI 应用

Responses API

生成图片

编辑图片

保存图片结果

其他接口

Gemini 原生协议

Claude 协议（Anthropic Messages）

处理调用错误

让编程助手读取文档

协议参考

​准备密钥与模型

​配置请求地址

​OpenAI 协议

​Chat Completions

​OpenAI SDK

​迁移已有 OpenAI 应用

​Responses API

​生成图片

​编辑图片

​保存图片结果

​其他接口

​Gemini 原生协议

​Claude 协议（Anthropic Messages）

​处理调用错误

​让编程助手读取文档

​协议参考

准备密钥与模型

配置请求地址

OpenAI 协议

Chat Completions

OpenAI SDK

迁移已有 OpenAI 应用

Responses API

生成图片

编辑图片

保存图片结果

其他接口

Gemini 原生协议

Claude 协议（Anthropic Messages）

处理调用错误

让编程助手读取文档

协议参考