Документация API429

1. Base URL и авторизация

Канонический base URL для клиентских запросов: https://balancer.api429.com/v1. Для всех запросов используйте Bearer-токен в заголовке Authorization.

curl https://balancer.api429.com/v1/models \
  -H "Authorization: Bearer ВАШ_ТОКЕН"

• Используйте https://balancer.api429.com/v1 как основной endpoint.
• GET /v1/models возвращает актуальный каталог моделей для вашего токена.
• Не публикуйте токен во фронтенде и публичных репозиториях.

2. Список моделей: /v1/models

Перед первым интеграционным вызовом получайте список доступных моделей именно своим токеном. Не опирайтесь на ручной список в документации как на единственный источник истины.

curl https://balancer.api429.com/v1/models \
  -H "Authorization: Bearer ВАШ_ТОКЕН"

• Используйте GET /v1/models перед production rollout и при синхронизации SDK.
• Список зависит от текущего токена и отражает реально доступные модели.

3. Каноническая система названий параметров

Канонический стиль именования в API429 — snake_case. Для image-роута дополнительно поддерживаются compatibility aliases в camelCase.

4. LLM генерация: /v1/chat/completions

Основной текстовый endpoint совместим с OpenAI-style chat API. Используйте messages, model и дополнительные canonical поля в snake_case.

curl -X POST https://balancer.api429.com/v1/chat/completions \
  -H "Authorization: Bearer ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-pro",
    "messages": [
      {"role": "user", "content": "Кратко объясни, как подключиться к API429."}
    ],
    "responseModalities": ["TEXT"],
    "thinkingLevel": "HIGH",
    "safetySettings": [
      {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"}
    ],
    "temperature": 0.3,
    "max_tokens": 300
  }'

import requests

url = "https://balancer.api429.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer ВАШ_ТОКЕН",
    "Content-Type": "application/json"
}
payload = {
    "model": "gemini-3.1-pro",
    "messages": [
        {"role": "user", "content": "Напиши короткий onboarding для клиента."}
    ],
    "responseModalities": ["TEXT"],
    "thinkingLevel": "MINIMAL",
    "safetySettings": [
        {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE"}
    ],
    "temperature": 0.2,
    "max_tokens": 200
}

response = requests.post(url, headers=headers, json=payload, timeout=180)
print(response.json())

• Проверено live: gemini-3.1-pro и gpt-5.1.
• Streaming включается через stream: true.
• responseModalities, thinkingLevel и safetySettings теперь принимаются и нормализуются на chat-route.

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Describe this concept briefly."}]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "thinkingConfig": {"thinkingLevel": "HIGH"}
  },
  "safetySettings": [
    {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"}
  ]
}

5. Image generation: /v1/images/generations

Для изображений используйте /v1/images/generations. Канонический стиль — snake_case, но для image-роута дополнительно поддерживаются camelCase aliases.

curl -X POST https://balancer.api429.com/v1/images/generations \
  -H "Authorization: Bearer ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "Футуристический мегаполис ночью, cinematic lighting",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "response_format": "b64_json"
  }'

import requests

url = "https://balancer.api429.com/v1/images/generations"
headers = {
    "Authorization": "Bearer ВАШ_ТОКЕН",
    "Content-Type": "application/json"
}
payload = {
    "model": "nano-banana-pro",
    "prompt": "Футуристический мегаполис ночью, cinematic lighting",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "response_format": "b64_json"
}

response = requests.post(url, headers=headers, json=payload, timeout=300)
result = response.json()
print(result)

• resolution работает. Поддерживаемые size tiers: 1K, 2K, 4K.
• aspect_ratio и aspectRatio работают.
• response_format: "b64_json" удобно для backend-интеграций.
• Важно: resolution задаёт целевой size tier, но не гарантирует exact returned pixel size. Гарантируется соблюдение aspect ratio, а не буквально запрошенных пикселей.
• Проверено live: и snake_case, и camelCase варианты параметров для image generation работают одинаково.

6. Проверка баланса: /api/client/balance

Если вам нужно проверить доступный баланс токена перед серией запросов, используйте отдельный client endpoint.

curl https://balancer.api429.com/api/client/balance \
  -H "Authorization: Bearer ВАШ_ТОКЕН"

• Endpoint возвращает текущее состояние баланса по Bearer-токену.
• Если у токена недостаточно средств, генерационные endpoints вернут 402 Insufficient Balance.

7. Частые ошибки

8. Практические рекомендации

• Для text/LLM запросов ставьте клиентский таймаут не меньше 60–180 секунд.
• Для image generation ставьте 120–300 секунд.
• Перед production rollout всегда делайте GET /v1/models и 1–2 smoke-запроса своим токеном.
• Если вам важны размеры изображения, ориентируйтесь на aspect ratio и size tier, а не на exact returned pixels.