> ## 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 开发文档

> GPT-5.6、Claude Sonnet 5、Gemini 3.6 Flash 等热门AI模型的统一API中文技术文档，包含Python、Node.js、Java、Go示例与错误处理。

## 为什么选择老张API？

老张API提供**企业级AI技术API接入服务**，解决开发者在使用多个AI模型时的支付门槛和接口统一问题。

## 服务特色

### OpenAI 兼容模式

老张API采用 **OpenAI 兼容格式**，统一接口调用200+AI模型：

**支持的模型厂商：**

* 🤖 **OpenAI**：gpt-5.6、gpt-5.6-terra、gpt-5.6-luna、gpt-5.1-codex 等
* 🧠 **Anthropic**：claude-sonnet-5、claude-opus-4-8、claude-fable-5 等
* 💎 **Google**：gemini-3.6-flash、gemini-3.5-flash-lite、gemini-3.1-pro-preview 等
* 🚀 **xAI**：grok-4.5、grok-4.3、grok-4.20 系列等
* 🔍 **DeepSeek**：deepseek-v4-pro、deepseek-v4-flash 等
* 🌟 **阿里**：Qwen 系列模型
* 💬 **Moonshot**：Kimi 模型等

<Note>
  模型是否可调用取决于当前账号、令牌分组和线路。正式接入前请在[控制台模型与价格页面](https://api2.laozhang.ai/account/pricing)确认准确模型 ID、实时价格和开放状态。
</Note>

### 功能支持范围

**✅ 支持的功能：**

* 💬 **对话补全**：Chat Completions接口
* 🖼️ **图像生成**：gpt-image-2、flux-kontext-pro、flux-kontext-max 等
* 🔊 **语音处理**：Whisper转录
* 📊 **嵌入向量**：文本向量化
* ⚡ **函数调用**：Function Calling
* 📡 **流式输出**：实时响应
* 🔧 **OpenAI参数**：temperature、top\_p、max\_tokens等
* 🆕 **Responses端点**：OpenAI最新功能

**❌ 不支持的功能：**

* 🔧 微调接口（Fine-tuning）
* 📁 Files管理接口
* 🏢 组织管理接口
* 💳 计费管理接口

### 简单切换模型

**核心优势：一套代码，多种模型**

用OpenAI格式跑通后，只要**更换模型名称**即可切换到其他大模型：

```python theme={null}
# 使用 GPT-5.6
response = client.chat.completions.create(
    model="gpt-5.6",  # OpenAI模型
    messages=[...]
)

# 切换到Claude，其他代码完全不变！
response = client.chat.completions.create(
    model="claude-sonnet-5",  # 只改模型名
    messages=[...]
)

# 切换到Gemini
response = client.chat.completions.create(
    model="gemini-3.6-flash",  # 只改模型名
    messages=[...]
)
```

<Tip>
  这种设计让您可以轻松对比不同模型的效果，或根据成本和性能需求灵活切换模型，无需重写代码！
</Tip>

## 快速开始 - API 技术接入

### 获取 API Key

<Warning>
  账号注册用于 API 技术接入测试与企业系统集成。laozhang.ai 由新加坡公司 YingTu Technology Pte. Ltd. 运营，注册与服务可用性以企业白名单审核为准；企业用户如需注册，请发送邮件至 `hi@laozhang.ai` 联系客服申请白名单开通。
</Warning>

1. 访问 [老张API控制台](https://api2.laozhang.ai/token)
2. 登录您的账户
3. 在令牌管理页面点击"新增"创建API Key
4. 复制生成的API Key用于接口调用

### 查看请求示例

在令牌管理页面，您可以快速获取各种编程语言的代码示例：

**操作步骤：**

1. 进入 [令牌管理页面](https://api2.laozhang.ai/token)
2. 找到您要使用的API Key所在的行
3. 点击"操作"列中的🔧**小扳手图标**（工具图标）
4. 在弹出菜单中选择"**请求示例**"
5. 查看包含以下语言的完整代码示例：

<img src="https://mintcdn.com/laozhangai-edd05f2c/_loZ0Jy0ZI__xJ9z/images/laozhang-token-dashboard.png?fit=max&auto=format&n=_loZ0Jy0ZI__xJ9z&q=85&s=e8ecad44193906296466f9778806aa11" alt="老张API令牌管理界面" width="1496" height="902" data-path="images/laozhang-token-dashboard.png" />

**支持的编程语言：**

* **cURL** - 命令行测试
* **Python (SDK)** - 使用官方OpenAI库
* **Python (requests)** - 使用requests库
* **Node.js** - JavaScript/TypeScript
* **Java** - Java应用开发
* **C#** - .NET应用开发
* **Go** - Go语言开发
* **PHP** - Web开发
* **Ruby** - Ruby应用开发
* 以及更多语言...

**代码示例特点：**

* ✅ **完整可运行**：复制粘贴即可使用
* ✅ **参数说明**：详细的参数配置
* ✅ **错误处理**：包含异常处理逻辑
* ✅ **最佳实践**：遵循各语言开发规范

<Note>
  建议开发者优先查看后台的请求示例，这些示例会根据最新的API版本实时更新，确保代码的准确性和可用性。
</Note>

## 基础信息

### API 端点

* **主要端点**：`https://api2.laozhang.ai/v1`（推荐，全球加速）
* **备用端点**：`https://api-vip.laozhang.ai/v1`（海外服务器可直连）

<Note>
  `api2.laozhang.ai` 配置了全球加速的宽带节点，建议优先使用。`api-vip.laozhang.ai` 仅作为备用域名，适合海外服务器直连，如遇不稳定请切换回主域名。
</Note>

### 认证方式

所有 API 请求需要在 Header 中包含认证信息：

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

### 请求格式

* **Content-Type**：`application/json`
* **编码格式**：UTF-8
* **请求方法**：POST（大部分接口）

## 核心接口

### 1. 对话补全（Chat Completions）

创建一个对话补全请求，支持多轮对话。

**请求端点**

```
POST /v1/chat/completions
```

**请求参数**

| 参数                 | 类型           | 必填 | 说明                        |
| ------------------ | ------------ | -- | ------------------------- |
| model              | string       | 是  | 模型名称，如 `gemini-3.6-flash` |
| messages           | array        | 是  | 对话消息数组                    |
| temperature        | number       | 否  | 采样温度，0-2之间，默认1            |
| max\_tokens        | integer      | 否  | 最大生成令牌数                   |
| stream             | boolean      | 否  | 是否流式返回，默认false            |
| top\_p             | number       | 否  | 核采样参数，0-1之间               |
| n                  | integer      | 否  | 生成数量，默认1                  |
| stop               | string/array | 否  | 停止序列                      |
| presence\_penalty  | number       | 否  | 存在惩罚，-2到2之间               |
| frequency\_penalty | number       | 否  | 频率惩罚，-2到2之间               |

**消息格式**

```json theme={null}
{
  "role": "system|user|assistant",
  "content": "消息内容"
}
```

**完整代码示例**

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api2.laozhang.ai/v1/chat/completions" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gemini-3.6-flash",
        "messages": [
          {"role": "system", "content": "你是一个有用的AI助手。"},
          {"role": "user", "content": "你好！请介绍一下自己。"}
        ],
        "temperature": 0.7,
        "max_tokens": 1000
      }'
    ```
  </Tab>

  <Tab title="Python (SDK)">
    ```python theme={null}
    from openai import OpenAI

    # 初始化客户端
    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api2.laozhang.ai/v1"
    )

    # 发送聊天请求
    response = client.chat.completions.create(
        model="gemini-3.6-flash",
        messages=[
            {"role": "system", "content": "你是一个有用的AI助手。"},
            {"role": "user", "content": "你好！请介绍一下自己。"}
        ],
        temperature=0.7,
        max_tokens=1000
    )

    print(response.choices[0].message.content)
    ```
  </Tab>

  <Tab title="Python (requests)">
    ```python theme={null}
    import requests
    import json

    url = "https://api2.laozhang.ai/v1/chat/completions"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }

    data = {
        "model": "gemini-3.6-flash",
        "messages": [
            {"role": "system", "content": "你是一个有用的AI助手。"},
            {"role": "user", "content": "你好！请介绍一下自己。"}
        ],
        "temperature": 0.7,
        "max_tokens": 1000
    }

    response = requests.post(url, headers=headers, json=data)
    result = response.json()

    if response.status_code == 200:
        print(result["choices"][0]["message"]["content"])
    else:
        print(f"错误: {result}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const OpenAI = require('openai');

    const client = new OpenAI({
      apiKey: 'YOUR_API_KEY',
      baseURL: 'https://api2.laozhang.ai/v1'
    });

    async function chatCompletion() {
      try {
        const response = await client.chat.completions.create({
          model: 'gemini-3.6-flash',
          messages: [
            {"role": "system", "content": "你是一个有用的AI助手。"},
            {"role": "user", "content": "你好！请介绍一下自己。"}
          ],
          temperature: 0.7,
          max_tokens: 1000
        });

        console.log(response.choices[0].message.content);
      } catch (error) {
        console.error('API调用错误:', error);
      }
    }

    chatCompletion();
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import okhttp3.*;
    import com.google.gson.Gson;
    import java.io.IOException;
    import java.util.*;

    public class LaoZhangExample {
        private static final String API_KEY = "YOUR_API_KEY";
        private static final String BASE_URL = "https://api2.laozhang.ai/v1";

        public static void main(String[] args) throws IOException {
            OkHttpClient client = new OkHttpClient();
            Gson gson = new Gson();

            // 构建请求体
            Map<String, Object> requestBody = new HashMap<>();
            requestBody.put("model", "gemini-3.6-flash");
            requestBody.put("temperature", 0.7);
            requestBody.put("max_tokens", 1000);

            List<Map<String, String>> messages = Arrays.asList(
                Map.of("role", "system", "content", "你是一个有用的AI助手。"),
                Map.of("role", "user", "content", "你好！请介绍一下自己。")
            );
            requestBody.put("messages", messages);

            RequestBody body = RequestBody.create(
                gson.toJson(requestBody),
                MediaType.parse("application/json")
            );

            Request request = new Request.Builder()
                .url(BASE_URL + "/chat/completions")
                .addHeader("Authorization", "Bearer " + API_KEY)
                .addHeader("Content-Type", "application/json")
                .post(body)
                .build();

            try (Response response = client.newCall(request).execute()) {
                System.out.println(response.body().string());
            }
        }
    }
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using System;
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json;

    class Program
    {
        private static readonly string API_KEY = "YOUR_API_KEY";
        private static readonly string BASE_URL = "https://api2.laozhang.ai/v1";

        static async Task Main(string[] args)
        {
            using var client = new HttpClient();
            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {API_KEY}");

            var requestBody = new
            {
                model = "gemini-3.6-flash",
                messages = new[]
                {
                    new { role = "system", content = "你是一个有用的AI助手。" },
                    new { role = "user", content = "你好！请介绍一下自己。" }
                },
                temperature = 0.7,
                max_tokens = 1000
            };

            var json = JsonConvert.SerializeObject(requestBody);
            var content = new StringContent(json, Encoding.UTF8, "application/json");

            try
            {
                var response = await client.PostAsync($"{BASE_URL}/chat/completions", content);
                var result = await response.Content.ReadAsStringAsync();
                Console.WriteLine(result);
            }
            catch (Exception ex)
            {
                Console.WriteLine($"错误: {ex.Message}");
            }
        }
    }
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    package main

    import (
        "bytes"
        "encoding/json"
        "fmt"
        "io/ioutil"
        "net/http"
    )

    type Message struct {
        Role    string `json:"role"`
        Content string `json:"content"`
    }

    type ChatRequest struct {
        Model       string    `json:"model"`
        Messages    []Message `json:"messages"`
        Temperature float64   `json:"temperature"`
        MaxTokens   int       `json:"max_tokens"`
    }

    func main() {
        apiKey := "YOUR_API_KEY"
        baseURL := "https://api2.laozhang.ai/v1"

        reqData := ChatRequest{
            Model: "gemini-3.6-flash",
            Messages: []Message{
                {Role: "system", Content: "你是一个有用的AI助手。"},
                {Role: "user", Content: "你好！请介绍一下自己。"},
            },
            Temperature: 0.7,
            MaxTokens:   1000,
        }

        jsonData, _ := json.Marshal(reqData)

        req, _ := http.NewRequest("POST", baseURL+"/chat/completions", bytes.NewBuffer(jsonData))
        req.Header.Set("Authorization", "Bearer "+apiKey)
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, err := client.Do(req)
        if err != nil {
            fmt.Printf("请求错误: %v\n", err)
            return
        }
        defer resp.Body.Close()

        body, _ := ioutil.ReadAll(resp.Body)
        fmt.Println(string(body))
    }
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    $api_key = 'YOUR_API_KEY';
    $base_url = 'https://api2.laozhang.ai/v1';

    $data = array(
        'model' => 'gemini-3.6-flash',
        'messages' => array(
            array('role' => 'system', 'content' => '你是一个有用的AI助手。'),
            array('role' => 'user', 'content' => '你好！请介绍一下自己。')
        ),
        'temperature' => 0.7,
        'max_tokens' => 1000
    );

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $base_url . '/chat/completions');
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Authorization: Bearer ' . $api_key,
        'Content-Type: application/json'
    ));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($http_code == 200) {
        $result = json_decode($response, true);
        echo $result['choices'][0]['message']['content'];
    } else {
        echo "错误: " . $response;
    }
    ?>
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'net/http'
    require 'json'

    api_key = 'YOUR_API_KEY'
    base_url = 'https://api2.laozhang.ai/v1'

    uri = URI("#{base_url}/chat/completions")
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    request = Net::HTTP::Post.new(uri)
    request['Authorization'] = "Bearer #{api_key}"
    request['Content-Type'] = 'application/json'

    request.body = {
      model: 'gemini-3.6-flash',
      messages: [
        { role: 'system', content: '你是一个有用的AI助手。' },
        { role: 'user', content: '你好！请介绍一下自己。' }
      ],
      temperature: 0.7,
      max_tokens: 1000
    }.to_json

    response = http.request(request)

    if response.code == '200'
      result = JSON.parse(response.body)
      puts result['choices'][0]['message']['content']
    else
      puts "错误: #{response.body}"
    end
    ```
  </Tab>
</Tabs>

**响应示例**

```json theme={null}
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1699000000,
  "model": "gemini-3.6-flash",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  }
}
```

### 2. 文本补全（Completions）

为兼容旧版接口保留，建议使用 Chat Completions。

**请求端点**

```
POST /v1/completions
```

**请求参数**

| 参数          | 类型           | 必填 | 说明     |
| ----------- | ------------ | -- | ------ |
| model       | string       | 是  | 模型名称   |
| prompt      | string/array | 是  | 提示文本   |
| max\_tokens | integer      | 否  | 最大生成长度 |
| temperature | number       | 否  | 采样温度   |
| top\_p      | number       | 否  | 核采样参数  |
| n           | integer      | 否  | 生成数量   |
| stream      | boolean      | 否  | 流式输出   |
| stop        | string/array | 否  | 停止序列   |

### 3. 嵌入向量（Embeddings）

将文本转换为向量表示。

**请求端点**

```
POST /v1/embeddings
```

**请求参数**

| 参数               | 类型           | 必填 | 说明                              |
| ---------------- | ------------ | -- | ------------------------------- |
| model            | string       | 是  | 模型名称，如 `text-embedding-3-small` |
| input            | string/array | 是  | 输入文本                            |
| encoding\_format | string       | 否  | 编码格式，`float` 或 `base64`         |

**完整代码示例**

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api2.laozhang.ai/v1/embeddings" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "text-embedding-3-small",
        "input": "这是一段需要向量化的文本示例"
      }'
    ```
  </Tab>

  <Tab title="Python (SDK)">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api2.laozhang.ai/v1"
    )

    response = client.embeddings.create(
        model="text-embedding-3-small",
        input="这是一段需要向量化的文本示例"
    )

    # 获取向量
    embedding = response.data[0].embedding
    print(f"向量维度: {len(embedding)}")
    print(f"前5个值: {embedding[:5]}")
    ```
  </Tab>

  <Tab title="Python (requests)">
    ```python theme={null}
    import requests
    import json

    url = "https://api2.laozhang.ai/v1/embeddings"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }

    data = {
        "model": "text-embedding-3-small",
        "input": "这是一段需要向量化的文本示例"
    }

    response = requests.post(url, headers=headers, json=data)
    result = response.json()

    if response.status_code == 200:
        embedding = result["data"][0]["embedding"]
        print(f"向量维度: {len(embedding)}")
        print(f"向量值: {embedding[:5]}")  # 显示前5个值
    else:
        print(f"错误: {result}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const OpenAI = require('openai');

    const client = new OpenAI({
      apiKey: 'YOUR_API_KEY',
      baseURL: 'https://api2.laozhang.ai/v1'
    });

    async function getEmbedding() {
      try {
        const response = await client.embeddings.create({
          model: 'text-embedding-3-small',
          input: '这是一段需要向量化的文本示例'
        });

        const embedding = response.data[0].embedding;
        console.log(`向量维度: ${embedding.length}`);
        console.log(`前5个值: ${embedding.slice(0, 5)}`);
      } catch (error) {
        console.error('API调用错误:', error);
      }
    }

    getEmbedding();
    ```
  </Tab>
</Tabs>

### 4. 图像生成（Images）

生成、编辑或变换图像。

**生成图像**

```
POST /v1/images/generations
```

**请求参数**

| 参数      | 类型      | 必填 | 说明                                         |
| ------- | ------- | -- | ------------------------------------------ |
| model   | string  | 是  | 模型名称，推荐 `gpt-image-2`                      |
| prompt  | string  | 是  | 图像描述提示词                                    |
| n       | integer | 否  | 生成数量，默认1                                   |
| size    | string  | 否  | 图像尺寸：`1024x1024`, `1792x1024`, `1024x1792` |
| quality | string  | 否  | 质量：`standard` 或 `hd`                       |
| style   | string  | 否  | 风格：`vivid` 或 `natural`                     |

<Note>
  推荐使用 `gpt-image-2` 模型进行图像生成。更多图像生成功能和参数说明，请查看 [GPT图像生成详细文档](/api-capabilities/gpt-image-2)。
</Note>

**完整代码示例**

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api2.laozhang.ai/v1/images/generations" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-image-2",
        "prompt": "一只可爱的橙色小猫坐在阳光明媚的花园里",
        "n": 1,
        "size": "1024x1024",
        "quality": "hd"
      }'
    ```
  </Tab>

  <Tab title="Python (SDK)">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api2.laozhang.ai/v1"
    )

    response = client.images.generate(
        model="gpt-image-2",  # 推荐使用gpt-image-2
        prompt="一只可爱的橙色小猫坐在阳光明媚的花园里",
        n=1,
        size="1024x1024",
        quality="hd"
    )

    # 获取图片URL
    image_url = response.data[0].url
    print(f"生成的图片: {image_url}")

    # 下载图片
    import requests
    img_response = requests.get(image_url)
    with open("generated_image.png", "wb") as f:
        f.write(img_response.content)
    print("图片已保存为 generated_image.png")
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const OpenAI = require('openai');
    const fs = require('fs');

    const client = new OpenAI({
      apiKey: 'YOUR_API_KEY',
      baseURL: 'https://api2.laozhang.ai/v1'
    });

    async function generateImage() {
      try {
        const response = await client.images.generate({
          model: 'gpt-image-2',  // 推荐使用gpt-image-2
          prompt: '一只可爱的橙色小猫坐在阳光明媚的花园里',
          n: 1,
          size: '1024x1024',
          quality: 'hd'
        });

        const imageUrl = response.data[0].url;
        console.log('生成的图片:', imageUrl);

        // 下载图片
        const fetch = require('node-fetch');
        const imgResponse = await fetch(imageUrl);
        const buffer = await imgResponse.buffer();
        fs.writeFileSync('generated_image.png', buffer);
        console.log('图片已保存');

      } catch (error) {
        console.error('生成图片错误:', error);
      }
    }

    generateImage();
    ```
  </Tab>
</Tabs>

### 5. 音频转文字（Audio）

语音识别和转录。

**转录音频**

```
POST /v1/audio/transcriptions
```

**请求参数**（Form-Data）

| 参数               | 类型     | 必填 | 说明                 |
| ---------------- | ------ | -- | ------------------ |
| file             | file   | 是  | 音频文件               |
| model            | string | 是  | 模型名称，如 `whisper-1` |
| language         | string | 否  | 语言代码               |
| prompt           | string | 否  | 指导提示               |
| response\_format | string | 否  | 响应格式               |
| temperature      | number | 否  | 采样温度               |

### 6. 模型列表

获取可用模型列表。

**请求端点**

```
GET /v1/models
```

**响应示例**

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "gemini-3.6-flash",
      "object": "model",
      "created": 1677610602,
      "owned_by": "google"
    },
    {
      "id": "claude-sonnet-5",
      "object": "model",
      "created": 1687882411,
      "owned_by": "anthropic"
    }
  ]
}
```

## 流式响应

### 开启流式输出

在请求中设置 `stream: true`：

```json theme={null}
{
  "model": "gemini-3.6-flash",
  "messages": [{"role": "user", "content": "Hello"}],
  "stream": true
}
```

### 流式响应格式

响应将以 Server-Sent Events (SSE) 格式返回：

```
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1699000000,"model":"gemini-3.6-flash","choices":[{"delta":{"content":"Hello"},"index":0}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1699000000,"model":"gemini-3.6-flash","choices":[{"delta":{"content":" there"},"index":0}]}

data: [DONE]
```

### 处理流式响应

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import requests
    import json

    response = requests.post(
        'https://api2.laozhang.ai/v1/chat/completions',
        headers={
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        },
        json={
            'model': 'gemini-3.6-flash',
            'messages': [{'role': 'user', 'content': 'Hello'}],
            'stream': True
        },
        stream=True
    )

    for line in response.iter_lines():
        if line:
            line = line.decode('utf-8')
            if line.startswith('data: '):
                data = line[6:]
                if data != '[DONE]':
                    chunk = json.loads(data)
                    content = chunk['choices'][0]['delta'].get('content', '')
                    print(content, end='')
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api2.laozhang.ai/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: 'gemini-3.6-flash',
        messages: [{role: 'user', content: 'Hello'}],
        stream: true
      })
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const {done, value} = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value);
      const lines = chunk.split('\n');

      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = line.slice(6);
          if (data !== '[DONE]') {
            const json = JSON.parse(data);
            const content = json.choices[0].delta.content || '';
            process.stdout.write(content);
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 错误处理

### 错误响应格式

```json theme={null}
{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
```

### 常见错误码

| 错误码                     | HTTP状态码 | 说明      |
| ----------------------- | ------- | ------- |
| invalid\_api\_key       | 401     | API密钥无效 |
| insufficient\_quota     | 429     | 额度不足    |
| model\_not\_found       | 404     | 模型不存在   |
| invalid\_request\_error | 400     | 请求参数错误  |
| server\_error           | 500     | 服务器内部错误 |
| rate\_limit\_exceeded   | 429     | 请求频率过高  |

### 错误处理示例

```python theme={null}
try:
    response = client.chat.completions.create(
        model="gemini-3.6-flash",
        messages=[{"role": "user", "content": "Hello"}]
    )
except Exception as e:
    if hasattr(e, 'status_code'):
        if e.status_code == 401:
            print("API密钥无效")
        elif e.status_code == 429:
            print("请求过于频繁或额度不足")
        elif e.status_code == 500:
            print("服务器错误，请稍后重试")
    else:
        print(f"未知错误：{str(e)}")
```

## 最佳实践

### 1. 请求优化

* **合理设置 max\_tokens**：避免不必要的长输出
* **使用 temperature**：控制输出的随机性
* **批量处理**：合并多个请求减少调用次数

### 2. 错误重试

实现指数退避的重试机制：

```python theme={null}
import time
import random

def retry_with_backoff(func, max_retries=3):
    for i in range(max_retries):
        try:
            return func()
        except Exception as e:
            if i == max_retries - 1:
                raise e
            wait_time = (2 ** i) + random.uniform(0, 1)
            time.sleep(wait_time)
```

### 3. 安全建议

* **保护API密钥**：使用环境变量存储
* **限制权限**：为不同应用创建不同的密钥
* **监控使用**：定期检查API使用日志

### 4. 性能优化

* **使用流式输出**：提升用户体验
* **缓存响应**：对相同请求缓存结果
* **并发控制**：合理控制并发请求数

## 速率限制

RPM、TPM 和并发限制会随模型、令牌分组、线路和账户配置变化，不使用统一固定值。请在控制台确认当前限制，并以渐进方式提高生产流量。

超出当前限制时通常会返回 429。客户端应读取错误信息，采用指数退避并限制重试次数；不要在未确认模型可用性和账户额度前持续重试。

## 需要帮助？

* 访问 [老张API官网](https://api2.laozhang.ai)
* 查看 [支持的模型](/api-capabilities/model-info)
* 联系技术支持：[hi@laozhang.ai](mailto:hi@laozhang.ai)

<Note>
  本手册持续更新中，请关注最新版本以获取新功能和改进。
</Note>