Справочник клиентского API WayGPT

Этот справочник описывает подключение своего приложения к WayGPT. Для обычной работы достаточно Studio: опишите задачу, приложите материалы и проверьте результат. Выбирать нейросеть перед каждым запросом не требуется.

Базовый адрес API: https://app.waygpt.ru/api/v1. Все примеры ниже относятся к существующему API. Они не создают новый договор на выполнение, не подтверждают готовность произвольной генерации и не включают оплату.

Выберите способ подключения

В браузерном кабинете используется вход через единый аккаунт и защищённая cookie-сессия. Кабинет получает доступ только к разрешённым рабочим пространствам и проектам.

Для собственного сервера используется ключ проекта в заголовке x-project-key. Получите его в настройках своего проекта и храните на сервере приложения. Не публикуйте ключ в JavaScript страницы, мобильном приложении, репозитории, примере запроса или журнале.

Cookie-сессию пользователя нельзя подменять ключом проекта. Не передавайте идентификатор чужого проекта и не используйте личный баланс вместо средств компании без отдельного подтверждённого условия.

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

Отправьте POST /api/v1/waygpt/chat/completions со своего сервера. Значение model: auto оставляет выбор способа выполнения сервису.

{
  "model": "auto",
  "messages": [
    {"role": "user", "content": "Объясни различия между двумя вариантами текста"}
  ],
  "stream": false,
  "store": true
}

Нужны заголовки Content-Type: application/json и x-project-key с ключом вашего проекта. В примере намеренно нет значения ключа: добавляйте его из защищённого хранилища своего сервера.

Текст ответа читается из choices[0].message.content, если такой ответ действительно получен. Не превращайте ошибку, пустое тело или оборванное соединение в успешный результат.

Продолжение диалога и сохранение

messages содержит сообщения текущего контекста. Для продолжения сохранённого диалога используйте session_id, полученный в рамках того же разрешённого проекта. Не подставляйте произвольный идентификатор из URL или другого рабочего пространства.

Обычный путь с model: auto использует store: true. В текущем API store: false — отдельный ограниченный режим для одиночного непотокового запроса: нужен явный доступный идентификатор модели, stream: false и отсутствие session_id. Значения auto, native и native-ai в этом режиме не поддерживаются; сочетание с ними возвращает ошибку 400.

Этот режим не поддерживает сценарии, веб-поиск и произвольные дополнительные параметры. Допустимые материалы и параметры проверяются отдельно; нельзя просто перенести в него любое вложение или настройку обычного запроса. Он не сохраняет текст переписки в истории WayGPT, но технические записи могут оставаться. store: false не означает отмену задачи, бесплатное выполнение или возможность восстановить несохранённый текст.

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

Потоковый ответ

stream: true включает потоковый ответ. Клиент должен читать события data: последовательно и собирать текстовые фрагменты, не отправляя новый запрос при каждом фрагменте.

Закрытие вкладки или SSE-соединения не является подтверждённой отменой. Если поток оборвался или получено событие ошибки, сохраните уже показанный текст как неподтверждённый результат и проверьте историю. Не считайте любое закрытие потока нормальным завершением.

Сохраняйте тип ошибки отдельно от текста ответа. Технические детали запроса и служебные сообщения не должны попадать в пользовательскую переписку или публичные журналы.

Каталог возможностей

GET /api/v1/waygpt/models возвращает доступные идентификаторы для подключения по ключу проекта. GET /api/v1/waygpt/models/full возвращает расширенные сведения, разрешённые этому подключению.

В кабинете GET /api/v1/client/models возвращает объекты с id, безопасным name и типом задачи. Идентификатор нужен запросу и значению элемента выбора; человеку показывайте name. Не извлекайте подписи из внутреннего идентификатора и не требуйте обязательного ручного выбора вместо auto.

Доступные форматы, параметры и ограничения нужно брать из текущего ответа сервиса. Не восстанавливайте неподдерживаемые настройки по названию модели и не добавляйте собственный расчёт стоимости.

Файлы и готовые материалы

В кабинете загрузка выполняется через POST /api/v1/client/uploads. Этот запрос требует действующего входа и разрешённого контекста проекта. Используйте multipart-форму и дождитесь ответа сервера до отправки основной задачи.

Сохраните asset_id из успешного ответа загрузки. Он связывает вложение с материалом сервиса; имя файла, MIME-тип и размер нужно показывать по серверному ответу. Ошибочная загрузка не должна исчезать незаметно или считаться приложенным файлом.

GET /api/v1/client/media показывает доступные материалы. GET /api/v1/client/media/{asset_id}/download скачивает материал после проверки доступа, а GET /api/v1/client/media/{asset_id}/share-url выдаёт разрешённую ссылку. Не делайте временную ссылку единственной записью о файле и не публикуйте её в открытом журнале.

GET /api/v1/client/media/output-formats описывает форматы результата. Это не обещание, что любой такой формат разрешён для загрузки как исходный файл.

Изображения, видео и фоновые задания

Существующие адреса выполнения: POST /api/v1/waygpt/images/generations и POST /api/v1/waygpt/videos/generations. Параметры выбирайте по текущим возможностям и ограничениям, а не по скопированному списку из инструкции.

Если получен идентификатор фонового задания, проверяйте GET /api/v1/waygpt/media/jobs/{job_id} в исходном проекте. POST /api/v1/waygpt/media/jobs/{job_id}/cancel отправляет команду отмены; её результат нужно показать пользователю. Отмена не доказывает автоматический возврат средств.

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

Для 3D и технических схем сначала задайте формат, единицы, назначение и требования к проверке. Используйте доступный сценарий Studio; не подменяйте настоящий файл изображением или обещанием о готовности.

История и сценарии кабинета

GET /api/v1/client/chat/history и GET /api/v1/client/chat/history/{session_id} относятся к разрешённой истории текущего пользователя. Не используйте их как публичный API чужих диалогов.

Сценарии проекта доступны в кабинете и через /api/v1/client/projects/{project_id}/use-cases: GET читает список, POST создаёт сценарий, PUT и DELETE работают с конкретной записью. Эти операции требуют входа и прав на проект. Для интеграции по ключу GET /api/v1/waygpt/use-cases показывает доступные сценарии.

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

Стоимость и баланс

Актуальные пакеты находятся на /pricing, опубликованные ставки использования — отдельно на /pricing/usage. GET /api/v1/public/pricing и GET /api/v1/public/wallet/offers являются публичными чтениями соответствующих каталогов.

Токены WayGPT — единицы баланса. Входные и выходные токены в справочных ставках измеряют объём обрабатываемых данных; это разные величины. Не вычисляйте цену произвольной задачи по названию, числу символов или внутренним параметрам.

Приём платежей готовится. Выбор пакета или своей суммы не означает оплату и зачисление. Не создавайте платёж по возврату на страницу, содержимому ссылки или клиентскому сообщению об успехе.

Ошибки и повторные попытки

400 означает, что нужно проверить формат и обязательные поля запроса. 401 — что нужно проверить вход или серверное подключение. 403 — что действие недоступно в выбранном контексте; не пытайтесь обойти права другим ключом.

429 означает временное ограничение запросов: выдержите паузу и проверьте состояние исходного действия. При 5xx или разрыве связи не запускайте повторную платную генерацию автоматически. Сначала восстановите известный статус; если это невозможно, обратитесь в поддержку.

Человеку показывайте понятное действие и состояние. Не выводите исходное тело ошибки, заголовки авторизации, ключи, временные ссылки или внутренние сведения о маршруте выполнения.

Проверка перед запуском

1. Вход, проект и права проверены реальным сервером. 2. Основной запрос работает с model: auto. 3. Вложения полностью загружены и относятся к исходному контексту. 4. Потоковый разрыв и статус ожидания не выглядят как готовый результат. 5. Готовый файл можно скачать и открыть повторно. 6. На телефоне доступны ввод, прикрепление и отправка; настройки не закрывают их. 7. Платёж и зачисление не обещаны до отдельной квалификации этого пути.

Продолжение: /docs/integration, /docs/files, /docs/billing и /docs/providers-and-models.