> ## 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.

# Как подключить приложение к LaoZhang API

> Создание API-ключа, запросы в форматах OpenAI, Anthropic и Gemini, генерация и редактирование изображений, перенос приложения с OpenAI — с рабочими примерами.

Отправляйте запросы на один из хостов из таблицы, указывая свой API-ключ LaoZhang API. OpenAI SDK работает с `https://api.laozhang.ai/v1`, а Google Gen AI SDK и Anthropic SDK используют корень хоста и сами добавляют свои пути.

| Домен | Когда использовать |
| - | - |
| `api.laozhang.ai` | По умолчанию; все примеры на сайте используют его |
| `api-vip.laozhang.ai` | Ваши серверы находятся в Европе или Северной Америке, и нужно прямое соединение |
| `api2.laozhang.ai` | `api.laozhang.ai` не открывается из вашей сети |

Все три домена принимают один и тот же API-ключ, пути и параметры, поэтому при переключении меняется только имя хоста. Консоль тоже открывается на каждом из них. Выберите формат запроса, который уже использует ваше приложение, и модель, доступную группе вашего ключа.

## Создание API-ключа

Создайте API-ключ в разделе [Управление токенами](https://api.laozhang.ai/token): в консоли он называется токеном. При создании вы выбираете группу и режим оплаты токена, а группа определяет, какие модели ключ может вызывать.

В качестве режима оплаты выберите «сначала по использованию» (в консоли — «按量优先», рекомендуется). Такой ключ вызывает и текстовые модели с оплатой по использованию, и модель изображений с оплатой за вызов, которые используются ниже. Обе настройки описаны в разделе [Тарификация, группы токенов и счета](https://docs.laozhang.ai/ru/pricing.md).

Сохраните ключ в переменной окружения в том терминале, где будете запускать примеры:

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
```

Замените заглушку своим ключом. Храните ключ на сервере: не добавляйте его в клиентские сборки, репозиторий и логи. AccessToken для управления аккаунтом — отдельные учётные данные, они нужны только для эндпоинтов аккаунта, например [API запроса баланса](https://docs.laozhang.ai/ru/api-capabilities/balance-query.md).

В примерах используются такие модели:

* `gpt-5.4-mini` — для текста
* `gemini-3.8-flash` — для нативных запросов Gemini
* `glm-5.2` — для Anthropic Messages
* `gpt-image-2.5-flare-vip` — для генерации изображений, `gpt-image-2.5-sunburst-vip` — для их редактирования

Чтобы взять другую модель, скопируйте её точный ID из раздела [Модели и цены](https://docs.laozhang.ai/ru/models.md) и проверьте, что группа вашего ключа может её вызывать. Как выбрать текстовую модель и формат запроса, описано в руководстве [API генерации текста](https://docs.laozhang.ai/ru/api-capabilities/text-generation.md).

## Текстовый запрос

Chat Completions принимает массив `messages`. API-ключ передаётся как Bearer-токен, тело запроса — JSON:

```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": "Ответь только одним словом: connected"}]
  }'
```

Ответ находится в `choices[0].message.content`; на этот промпт ожидается `connected`. Чтобы использовать тот же запрос в своём приложении, подставьте собственный текст сообщения. Поля сообщений, потоковую передачу и параметры отдельных моделей описывает [справочник по протоколу OpenAI](https://docs.laozhang.ai/ru/api-reference/chat-completions.md).

## Подключение через OpenAI SDK

OpenAI SDK сам формирует путь эндпоинта, поэтому задайте базовый URL `https://api.laozhang.ai/v1` без суффикса `/chat/completions`.

> [tab] Python
>
> Установите SDK:
>
> ```bash theme={null}
> python -m pip install openai
> ```
>
> ```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": "Ответь только одним словом: connected"}],
> )
> print(response.choices[0].message.content)
> ```

> [tab] Node.js
>
> Установите SDK командой `npm install openai`, сохраните код в файл с расширением `.mjs` и запустите его через 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: "Ответь только одним словом: connected" }],
> });
> console.log(response.choices[0].message.content);
> ```

В примерах автоматические повторные попытки SDK отключены: так приложение само решает, когда повторять запрос.

Тот же клиент работает и с эндпоинтами Responses, Images, Audio, Embeddings и Moderations. Какой эндпоинт нужен каждой модели OpenAI, включая `o3-pro`, GPT Image и речевые модели, показано в разделе [Модели OpenAI в LaoZhang API](https://docs.laozhang.ai/ru/api-reference/openai.md).

### Перенос существующего приложения с OpenAI

Приложению, которое уже работает через OpenAI SDK, нужно изменить три вещи: API-ключ и базовый URL в клиенте (ниже) и значение `model` в каждом запросе. Остальной код запросов остаётся прежним.

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

Если приложение настраивает SDK только через переменные окружения, переключиться можно без правки кода. Python- и Node.js-версии OpenAI SDK читают `OPENAI_API_KEY` и `OPENAI_BASE_URL`:

```bash theme={null}
export OPENAI_API_KEY="$LAOZHANG_API_KEY"
export OPENAI_BASE_URL="https://api.laozhang.ai/v1"
```

Перед отправкой рабочего трафика проверьте следующее:

* **ID моделей.** Название модели, которое работает у OpenAI, в LaoZhang API может иметь другой ID или другую группу. Копируйте точные ID из раздела [Модели и цены](https://docs.laozhang.ai/ru/models.md); остальные отличия от прямых вызовов OpenAI перечислены в [руководстве по моделям OpenAI](https://docs.laozhang.ai/ru/api-reference/openai.md).
* **Необязательные параметры.** Параметры сэмплирования, лимиты вывода, структурированный вывод и настройки инструментов зависят от модели. Начните с обязательных полей, затем добавляйте нужные опции. Если запрос вернул ошибку о неподдерживаемом параметре, уберите или измените указанное в ошибке поле.
* **Повторные попытки.** Держите логику повторов в одном месте. Если повторяют и SDK, и приложение, одно действие пользователя породит несколько вызовов API.
* **Результат.** Выполните минимальный запрос выше, найдите его в [журнале вызовов](https://api.laozhang.ai/log) и сверьте модель, расход токенов и списанную сумму.

Чтобы вернуться назад, восстановите прежние API-ключ и базовый URL.

## Responses API

Responses API принимает в запросе поле `input` и возвращает массив `output`. Тело запроса отличается от Chat Completions, поэтому при переходе нужно изменить и сам запрос, и разбор ответа.

> [tab] 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": "Ответь только одним словом: connected"
>   }'
> ```

> [tab] Python
>
> Используйте тот же пакет `openai`, что установлен выше:
>
> ```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="Ответь только одним словом: connected",
> )
> print(response.output_text)
> ```

В сыром JSON соберите значения `text` из элементов содержимого типа `output_text` внутри массива `output`. Хелпер SDK делает это за вас. Другие элементы массива могут содержать рассуждения или вызовы инструментов, поэтому первый элемент не обязательно является текстовым ответом.

LaoZhang API поддерживает Responses API от OpenAI, так что его могут использовать текстовые модели OpenAI, например GPT-6, GPT-5.6, GPT-5.4 и `o3-pro`. Прежде чем переводить на этот эндпоинт модель другого вендора, отправьте минимальный запрос и убедитесь, что она работает.

Серверное хранение диалога, `previous_response_id` и встроенные инструменты тоже зависят от модели. Если приложению нужна история диалога, храните сообщения, которые понадобятся следующему запросу. Поля описаны в [справочнике OpenAI по Responses](https://developers.openai.com/api/reference/resources/responses/methods/create), а обработка данных — в [Политике данных](https://www.laozhang.ai/data-policy).

## Генерация и редактирование изображений

Оба эндпоинта Images возвращают массив `data`. В зависимости от модели каждый элемент содержит изображение в Base64 в поле `b64_json` или ссылку для скачивания в поле `url`.

В примерах используются модели GPT Image 2.5 VIP: они оплачиваются за вызов, тогда как текстовые примеры оплачиваются по использованию. Ключ с режимом «сначала по использованию» вызывает и те и другие; если запрос на изображение отклонён, проверьте, что [режим оплаты](https://docs.laozhang.ai/ru/pricing.md) ключа — «сначала по использованию» (按量优先) или «оплата за вызов» (按次计费).

### Генерация изображения

Отправьте промпт в 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.5-flare-vip",
    "prompt": "Синяя керамическая чашка на белом столе, мягкий естественный свет, предметная съёмка."
  }' \
  -o generation.json
```

### Редактирование изображения

Положите референсное изображение `input.png` в текущую папку и отправьте его вместе с инструкцией как multipart/form-data:

```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.5-sunburst-vip" \
  -F "image[]=@input.png" \
  -F 'prompt=Замени фон на бледно-голубой. Объект не меняй.' \
  -o edit.json
```

Символ `@` загружает содержимое файла. Тип содержимого multipart и boundary выставит сам cURL, поэтому не добавляйте в этот запрос заголовок `Content-Type: application/json`.

### Сохранение результата

Файл ответа — это JSON, а не изображение. Сохраните этот скрипт как `save_images.py`; он использует только стандартную библиотеку Python:

```python theme={null}
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"В {source} нет изображений: {response}")

for index, item in enumerate(items, start=1):
    if item.get("b64_json"):
        # Убираем префикс data:image/...;base64, и добавляем недостающий padding
        encoded = re.sub(r"^data:[^,]*,", "", item["b64_json"].strip())
        raw = base64.b64decode(encoded + "=" * (-len(encoded) % 4))
    elif item.get("url"):
        # Скачиваем по ссылке без API-ключа
        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"Сохранено: {output}")
```

Запустите его для любого из файлов ответа:

```bash theme={null}
python save_images.py generation.json
python save_images.py edit.json
```

Скрипт сохраняет все изображения из `data`, например `generation-1.png`. Он обрабатывает:

* Base64 с префиксом `data:image/...;base64,` или без завершающего padding `=`.
* Результаты в виде `url`: он скачивает их без вашего API-ключа. Сохраняйте такие файлы сразу и держите собственную копию.

Примеры работы с обеими операциями через Python SDK есть в [справочнике Images API](https://docs.laozhang.ai/ru/api-reference/images.md). Размеры, качество и форматы вывода зависят от модели; когда добавляете их, пользуйтесь руководством по нужной модели.

## Нативный API Gemini

Нативный API Gemini использует `contents[].parts[]` вместо сообщений OpenAI:

```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": "Ответь только одним словом: connected"}]
    }]
  }'
```

Текст находится в частях `candidates[].content.parts[]`. Если текста нет, проверьте `finishReason` и `promptFeedback`.

Для Google Gen AI SDK используйте корень хоста `https://api.laozhang.ai` и `api_version="v1beta"`: SDK сам добавит путь модели и заголовок с ключом. В [справочнике по протоколу Gemini](https://docs.laozhang.ai/ru/api-reference/gemini.md) есть полный пример на Python, оба варианта заголовка авторизации и инструкции по передаче изображений, PDF и аудио. Анализ кадров и звука из видео MP4 описан в разделе [API понимания видео](https://docs.laozhang.ai/en/api-capabilities/video-understanding.md).

## API Anthropic Messages

Приложения на формате Anthropic Messages, в том числе на Anthropic SDK, отправляют запросы на `/v1/messages`:

```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": "Ответь только одним словом: connected"}]
  }'
```

* **Обязательные поля:** `model`, `messages` и `max_tokens`.
* **Системный промпт:** передавайте его в поле `system` верхнего уровня, а не в `messages`.
* **Ответ:** массив `content` может содержать блоки `text`, `thinking` и `tool_use`.
* **Текст ответа:** читайте блоки с `type`, равным `text`, и не считайте первый блок ответом.

Эндпоинт Messages обслуживает модели с пометкой Anthropic Messages в разделе [Модели и цены](https://docs.laozhang.ai/ru/models.md):

* Модели Claude, снова доступные с 18 октября 2026 года, например `claude-sonnet-5-5` и `claude-opus-5-5`. Чем они отличаются от собственного API Anthropic, описано в разделе [ограничения моделей Claude](https://docs.laozhang.ai/ru/api-reference/claude.md).
* `glm-5.2` из группы токенов `default` ведёт себя почти так же, как собственный Messages API Anthropic.
* `deepseek-v4-pro` и `deepseek-v4-flash` тоже помечены для этого эндпоинта.

Для Anthropic Python SDK передайте `base_url="https://api.laozhang.ai"` и свой API-ключ LaoZhang API: SDK сам добавит `/v1/messages`. SDK, потоковую передачу и вызов инструментов описывает [справочник по протоколу Claude](https://docs.laozhang.ai/ru/api-reference/claude.md).

## Другие операции API

* [Models API](https://docs.laozhang.ai/en/api-reference/models.md): список ID моделей для вашего приложения.
* [Эмбеддинги](https://docs.laozhang.ai/en/api-capabilities/text-embedding.md): преобразование текста в векторы.
* [Транскрипция аудио](https://docs.laozhang.ai/en/api-capabilities/audio-transcription.md): загрузка аудио и получение расшифровки.

## Частые ошибки

| Статус | Что проверить |
| - | - |
| 400 | Синтаксис JSON, типы полей, опции модели и длину входных данных. |
| 401 | API-ключ, заголовок авторизации и срок действия ключа. |
| 403 | Группу токена, права на модель и ограничения аккаунта. |
| 404 | Итоговый URL и точный ID модели; ищите задвоенный `/v1`. |
| 429 | Тело ошибки: лимит скорости, параллельности, ёмкости или недостаток баланса. |
| 5xx или таймаут | Состояние сети, доступность модели и журнал вызовов. |

Исправляйте некорректные запросы до повторной отправки. При временных сбоях используйте повторы с ограниченной задержкой и не накладывайте повторы SDK на повторы приложения.

Таймаут на стороне клиента не отменяет генерацию и не показывает, было ли списание. Прежде чем повторно отправлять запрос на изображение, проверьте [журнал вызовов](https://api.laozhang.ai/log).

За помощью пишите на [hi@laozhang.ai](mailto:hi@laozhang.ai) или в Telegram [@laozhang\_cn](https://t.me/laozhang_cn), указав время запроса, модель, эндпоинт, группу токена и ошибку без секретных данных. Оплата и возвраты регулируются [Условиями использования](https://www.laozhang.ai/terms).

## Документация в ИИ-инструментах для программирования

Передайте ассистенту модель, задачу и один из этих файлов:

* [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): индекс страниц и полный текст документации. Сейчас оба файла содержат китайскую версию.

Передавайте учётные данные через окружение, а не вставляйте их в промпты.

## Справочники API

Справочники LaoZhang API:

* [API генерации текста: выбор протокола и модели](https://docs.laozhang.ai/ru/api-capabilities/text-generation.md)
* [Модели OpenAI: эндпоинты и настройка SDK](https://docs.laozhang.ai/ru/api-reference/openai.md)
* [Протокол OpenAI: Chat Completions](https://docs.laozhang.ai/ru/api-reference/chat-completions.md)
* [Протокол Claude: Anthropic Messages](https://docs.laozhang.ai/ru/api-reference/claude.md)
* [Протокол Gemini: generateContent](https://docs.laozhang.ai/ru/api-reference/gemini.md)
* [Images API: генерация и редактирование изображений](https://docs.laozhang.ai/ru/api-reference/images.md)
* [Models API](https://docs.laozhang.ai/en/api-reference/models.md)

Поля запросов и возможности моделей определяют официальные справочники провайдеров. ID моделей, доступ и цены в LaoZhang API указаны в разделе [Модели и цены](https://docs.laozhang.ai/ru/models.md) и в [консоли](https://api.laozhang.ai/account/pricing).

* OpenAI: [API reference](https://developers.openai.com/api/reference/overview), [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/models)
* Anthropic: [Messages API](https://platform.claude.com/docs/en/api/messages)
* Google: [документация Gemini API](https://ai.google.dev/gemini-api/docs) и [справочник generateContent](https://ai.google.dev/api/generate-content)

Для Alibaba Cloud, ByteDance, xAI, Black Forest Labs, DeepSeek и других вендоров смотрите [официальную документацию API по вендорам](https://docs.laozhang.ai/en/resources.md): там же указано, какое руководство LaoZhang API соответствует каждому вендору.


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