API без шаманства

Обзор Pinegate API

Pinegate — единая OpenAI-совместимая точка доступа к текстовым и embedding-моделям разных провайдеров. Один API-ключ, единый баланс и знакомый формат запросов.

Быстрый старт

Если инструмент уже умеет работать с OpenAI API, обычно достаточно заменить base URL и вставить ключ Pinegate.

Авторизация

Передавай ключ в каждом запросе через HTTP-заголовок:

Authorization: Bearer YOUR_API_KEY

Модели и их ID

Каталог меняется без выпуска новой версии документации. Получай доступные именно твоему ключу модели через GET /v1/models.

curl https://pinegate.xyz/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Как читать ID

• openai/gpt-5.6-sol — провайдер и конкретный маршрут.
• Передавай точный ID модели без сокращений и переименования.
• Модель может исчезнуть, быть заменена или временно отключена upstream-провайдером.
• Цена и контекст зависят от маршрута; сверяйся с актуальной страницей цен.

Матрица endpoint’ов

Чат и генерация текста

Основной endpoint совместим с форматом Chat Completions.

Актуальный каталог не зашит в документацию: получай его запросом GET /v1/models или смотри страницу цен.

Streaming (SSE)

Добавь "stream": true, чтобы получать ответ частями. Сервер отправляет события data: {...}; завершение обозначается data: [DONE].

{
  "model": "openai/gpt-5.6-sol",
  "messages": [{"role":"user","content":"Hello"}],
  "stream": true,
  "stream_options": {"include_usage": true}
}

• Текст обычно приходит в choices[0].delta.content.
• Не склеивай JSON-строки как обычный текст: разбирай каждое SSE-событие отдельно.
• include_usage просит финальную статистику usage, если маршрут её поддерживает.
• При обрыве соединения не повторяй запрос вслепую, если результат уже мог частично обработаться.

Tools / Function calling

Проверенная модель openai/gpt-5.4-nano может выбрать описанную тобой функцию, но Pinegate не выполняет её за тебя. Приложение получает tool_calls, вызывает свой код и отправляет результат следующим сообщением с ролью tool.

{
  "model": "openai/gpt-5.4-nano",
  "messages": [{"role":"user","content":"Какая погода в Казани?"}],
  "tools": [{"type":"function","function":{
    "name":"get_weather",
    "description":"Получить погоду",
    "parameters":{"type":"object","properties":{
      "city":{"type":"string"}
    },"required":["city"]}
  }}]
}

Embeddings

Векторные представления нужны для семантического поиска, кластеризации и RAG.

curl https://pinegate.xyz/v1/embeddings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"baai/bge-m3-embedding","input":["Первый текст","Второй текст"]}'

В ответе массив data[].embedding. Размерность зависит от модели. Не смешивай в одном индексе векторы, созданные разными моделями.

Reasoning

Для моделей с управляемым рассуждением передавай уровень через reasoning_effort.

{
  "model": "openai/gpt-5.6-sol",
  "messages": [{"role": "user", "content": "Solve this carefully"}],
  "reasoning_effort": "high"
}

Usage и токены

Не-streaming ответ содержит объект usage. В live-тесте Pinegate вернул токены и точную стоимость запроса.

"usage": {
  "prompt_tokens": 11,
  "completion_tokens": 19,
  "total_tokens": 30,
  "completion_tokens_details": {"reasoning_tokens": 12},
  "cost": 0.00008514
}

Тарификация

Pinegate работает по предоплате: расходы списываются с баланса по фактическому использованию конкретной модели.

• Цена входных и выходных токенов может различаться.
• Reasoning и embeddings могут тарифицироваться иначе.
• Обрезанный клиентом ответ всё равно может содержать уже сгенерированные и оплаченные токены.
• Актуальная цена в интерфейсе приоритетнее примеров в документации.

Ошибки и диагностика

Безопасный retry

• Повторяй 429, 502, 503 и сетевые ошибки через 1, 2, 4, 8 секунд + случайный jitter.
• Задай максимум попыток и общий deadline.
• Не повторяй 400, 401 и ошибку баланса, пока не исправлена причина.

Интеграции

Везде используется один адрес и один ключ. Названия полей отличаются у конкретных приложений.

FAQ

Нужно ли дописывать /v1?

Если поле называется Base URL — обычно укажи https://pinegate.xyz/v1. Если клиент сам добавляет /v1, используй адрес без дублирования.

Почему модель есть в списке, но параметр не работает?

OpenAI-совместимость описывает форму API, но не гарантирует поддержку каждой функции конкретной моделью. Убери спорный параметр и проверь документацию маршрута.

Почему ответ обрезан?

Проверь finish_reason, лимит output/max_tokens, размер контекста и timeout клиента.

Что отправлять поддержке?

UTC-время, endpoint, модель, HTTP-код, безопасный фрагмент ошибки и request_id. Никогда не отправляй API-ключ, полный приватный prompt или персональные данные.