|

Документация APIYI по поиску Request ID обновлена и оптимизирована: два способа получения — из исходного текста ошибки и из заголовков ответа

Документация APIYI по поиску Request ID обновлена и оптимизирована: два способа получения — из исходного текста ошибки и из заголовков ответа

Примечание автора: документация APIYI по поиску Request ID обновлена. В этой статье разберём, какую именно строку копировать при ошибке, какие ID использовать нельзя, как сохранять task_id асинхронных видео-задач и какие материалы приложить, если в логах ничего не находится.

Когда после ошибки вызова разработчик открывает тикет, он часто застревает на одном и том же: у него на руках есть какая-то строка ID, а служба поддержки не может найти её в логах. Причина, как правило, в том, что скопирован X-Request-Id от вышестоящего провайдера, а не собственный X-Shellapi-Request-Id от APIYI. Новую документацию переписали именно для решения этой проблемы, адрес: docs.apiyi.com/faq/request-id-troubleshooting.

Это не просто документация с новым оформлением. Старая версия начиналась с «заголовков ответа» и была полна слов «обычно» и «возможно» — после прочтения всё равно непонятно, где что копировать. В новой версии порядок обратный: сначала ответ, потом способ получения, а в конце шаблон тикета.

Главная ценность: после прочтения этой статьи вы за 10 секунд сможете получить правильный Request ID и научитесь отличать неверные ID. А если записи в логах не найдётся, вы будете знать, какие материалы приложить.

apiyi-request-id-docs-upgrade-ru-image-0


Что изменилось в обновлённой документации APIYI по Request ID

Ответ есть в первой же фразе новой версии страницы: Request ID в APIYI — это заголовок ответа X-Shellapi-Request-Id, и при ошибке в конце сообщения об ошибке указывается то же самое значение. Заодно поправили несколько мест на старой странице, где x-request-id описывался примерно как «запишите, чтобы удобнее было разбираться».

Пункт Детали
Дата обновления 2026-11-16
Где в документации Раздел FAQ, новая версия страницы «Диагностика по Request ID»
Главный ответ Request ID = заголовок ответа X-Shellapi-Request-Id; (request id: ...) в конце сообщения об ошибке — это то же значение
Что добавили Два способа получить ID, таблица соответствия ID, отсутствие ID в логах консоли, пояснение про асинхронное видео, что делать, если ID не находится, шаблон тикета
Безопасность Request ID — не ключ, его можно вставлять в тикеты, чаты и скриншоты; наружу нельзя передавать только полный API Key, начинающийся с sk-
Кого затрагивает Всех разработчиков, которые вызывают в APIYI текстовые и графические модели, Embedding, Claude Messages, Responses и асинхронные видеоинтерфейсы

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


Request ID в APIYI: какую строку копировать — два пути

Сначала о формате: Request ID в APIYI начинается с 14-значного UTC-времени. Например, 2026111602224568279882196e93ae3kTS58ypN — первые 14 символов 20261116022245 это 2026-11-16 02:22:45 UTC, то есть 10:22:45 по пекинскому времени. Сверьте этот префикс со временем своего вызова — по нему в основном можно понять, не перепутали ли вы строку.

apiyi-request-id-docs-upgrade-ru-image-1

Путь 1: копирование прямо из JSON ошибки

Этот вариант подойдёт большинству пользователей клиентов. При ошибке в конце поля message в JSON ошибки будет фрагмент (request id: ...) — просто скопируйте всю строку в скобках целиком.

  1. Найдите полный JSON ошибки в клиенте или в выводе логов.
  2. Найдите конец поля message.
  3. Скопируйте всю строку символов после request id:, не обрезая её.

Логи консоли: вызов подтвердить можно, но Request ID там не отображается

Многие первым делом лезут на страницу «Логи» в консоли искать ID. В новой документации этому посвящён отдельный раздел: на странице логов X-Shellapi-Request-Id не показывается, и поиска по нему тоже нет.

В логах видно время, модель, имя токена, потоковый/непотоковый режим, длительность, статус, входные/выходные токены, стоимость, группу, множитель и IP. Этого достаточно, чтобы понять, дошёл ли вызов до APIYI, какая модель использовалась и сколько списали денег, но как идентификатор для обращения в поддержку это не годится.

Поэтому при обращении в поддержку ID берут только из двух источников: текста ошибки (путь первый) и заголовков ответа (путь второй). Логи нужны, чтобы добавить время, модель, токен и стоимость.

Путь второй: читаем заголовок ответа в коде

Если вы автоматически собираете ошибки, советую записывать этот заголовок прямо в коде. Во всех вариантах Base URL должен быть https://api.apiyi.com/v1.

  1. cURL: добавьте curl -D headers.txt, чтобы записать заголовки ответа в файл, а затем ищите в файле x-shellapi-request-id. Для разовой проверки можно просто вывести их через curl -i.
  2. Python requests: после получения объекта ответа читайте r.headers.get("x-shellapi-request-id"). Это работает и при успешном ответе, и при ошибке.
  3. OpenAI SDK (Python): в обычном возвращаемом значении _request_id читается из x-request-id, а в APIYI он обычно пустой. Правильный способ — использовать client.chat.completions.with_raw_response.create(...), читать raw.headers.get("x-shellapi-request-id"), а затем получать результат через raw.parse(). При ошибке читайте e.response.headers в except openai.APIStatusError as e.
  4. Node.js: при использовании fetch читайте res.headers.get("x-shellapi-request-id").
  5. Postman: после отправки запроса откройте вкладку Headers в области ответа и найдите X-Shellapi-Request-Id.
  6. Фронтенд в браузере: при кросс-доменных вызовах CORS не даёт JS прочитать этот заголовок. Его можно записать в бэкенд-прокси или посмотреть в инструментах разработчика: Network → нужный запрос → Response Headers.

🚀 Быстрая проверка: чтобы убедиться, что ваш код читает этот заголовок, отправьте минимальный запрос с токеном APIYI apiyi.com и посмотрите, удаётся ли вывести ID, начинающийся с 14-значной временной метки. Это потратит немного токенов, поэтому лучше выбрать промпт с очень коротким ответом.


Какие ID не являются Request ID APIYI

В одном ответе может одновременно появиться несколько видов «ID», и многие обращения в поддержку застревают именно на этом шаге. В новой документации есть сравнительная таблица — ниже собрал главное.

apiyi-request-id-docs-upgrade-ru-image-2

Поле Источник Можно ли использовать для обращения в поддержку и поиска логов Признак
X-Shellapi-Request-Id APIYI ✅ Это он начинается с 14-значной метки времени UTC
X-Oneapi-Request-Id Промежуточный слой ❌ другое имя заголовка
X-Request-Id Исходный провайдер (upstream) ❌ В логах APIYI не найти обычно начинается с req_ или UUID
Пользовательские заголовки других каналов Канал ❌ имена заголовков различаются
id в теле ответа Completion ID / Response ID ❌ начинается с chatcmpl-, resp_
generation_id изображения Результат генерации изображения ❌ находится в теле ответа
task_id Асинхронная задача ❌ Не Request ID, но нужно указывать вместе для поиска задачи и проверки списаний

Правило простое: если ID не начинается с 14-значной метки времени, это не Request ID от APIYI. Если вам дали ID, начинающийся с req_, возможно, запрос ушёл напрямую в официальный OpenAI. В этом случае сначала проверьте, не указан ли Base URL как https://api.apiyi.com/v1.


Как раздельно хранить task_id и Request ID для асинхронных видео

У асинхронных видео есть два шага — «отправка» и «опрос статуса», и каждый возвращает новый X-Shellapi-Request-Id, плюс есть ещё ID задачи. Всё это легко смешать в кучу. Совет из новой версии документации: храните Request ID запроса на отправку и ID задачи для опроса отдельно друг от друга.

Модель Где лежит ID задачи Интерфейс опроса Что легко перепутать
Seedance id на верхнем уровне тела ответа (поле называется не task_id) GET /seedance/api/v3/contents/generations/tasks/{id} —
Wan / HappyHorse output.task_id GET /v1/tasks/{task_id} request_id в теле ответа — это идентификатор апстрима, а не тот, что в логах APIYI

На практике для каждой задачи стоит хранить три поля: X-Shellapi-Request-Id на момент отправки, ID задачи и время отправки. Request ID, который возвращается при опросе задачи, можно записывать по желанию. Если отправка не удалась — для обращения в поддержку используйте Request ID; если задача зависла или есть вопросы по списанию средств, ID задачи понадобится и для проверки самой задачи, и для проверки списания.


Что приложить, если Request ID не находится в логах

Даже если ID получен, в логах он найдётся не обязательно. В новой версии документации случай «в журнале консоли нет Request ID» вынесен в отдельный раздел, а ещё несколько ситуаций, когда ID не удаётся найти, можно разобрать по таблице.

Ситуация Причина Что приложить
Запрос завершился ошибкой до получения ответа DNS, TCP/TLS, отказ прокси, тайм-аут клиента — заголовков ответа вообще нет Исходный текст ошибки, время вызова, описание сетевой среды
Клиент показывает только «запрос не удался» Клиент не показывает исходную ошибку Получить ID по пути 1 или пути 2; логи позволяют лишь подтвердить, дошёл ли вызов
ID начинается с req_ Возможно, запрос ушёл напрямую в OpenAI Проверить Base URL и повторить запрос
В логах тоже не находится Срок хранения истёк или ID перепутан Проверить формат ID; в логах хранятся только текущий и два предыдущих календарных месяца

Ещё один момент: страница консоли не показывает ID, но API поиска по логам умеет искать по request_id. В таблице ниже — проверка реальных вызовов от 2026-11-16 для моделей deepseek-flash и gpt-image-2; запросы отправлялись на https://api.apiyi.com/v1.

Вызов HTTP-статус Заголовки ответа Результат поиска в логах по request_id
deepseek-flash, без стриминга 200 есть x-shellapi-request-id, нет x-request-id точно нашлась 1 строка списания
deepseek-flash, стриминговый 200 есть, читается ещё до первого блока data: —
gpt-image-2, size=999×999 400 совпадает с request id в конце message 3 строки ошибок/повторов, строки списания нет
Несуществующее имя модели 503 совпадает с request id в конце message не находится ни одной строки

Вывод: страница журнала в консоли не показывает Request ID, но API поиска по логам умеет находить по request_id «строки списания» и «строки ошибок», причём их наличие не гарантируется. Если запрос дошёл до канала и уже там завершился ошибкой (например, из-за неверных параметров), останется строка ошибки. Если запрос отклонён сразу на уровне шлюза (например, нет доступного канала), может не оказаться ни одной строки. Когда ID не находится, приложите ID из заголовков ответа или исходного текста ошибки вместе со временем вызова.

Если поддержке нужно воспроизвести проблему, можно в APIYI apiyi.com повторно вызвать тот же эндпоинт с тем же токеном и тем же набором параметров — или взять другую модель и сравнить, будет ли та же ошибка. Воспроизведение тоже расходует токены, поэтому записывайте Request ID каждого повторного вызова.

🎯 Совет по диагностике: при воспроизведении ошибки фиксируйте Base URL как https://api.apiyi.com/v1 и каждый раз записывайте X-Shellapi-Request-Id и время вызова. Затем передайте поддержке ID и время вызова — бэкенд найдёт по ID и быстрее определит, на каком уровне произошла ошибка: на шлюзе или в канале.


Шаблон тикета об ошибке Request ID в APIYI

Просто скопируйте эти поля в тикет и заполните их:

  • Request ID: строка, начинающаяся с 14-значной метки времени
  • Модель: например, gpt-image-2
  • Эндпоинт: например, POST /v1/chat/completions
  • Время: с указанием часового пояса, например, 2026-11-16 11:24:04 UTC+8
  • HTTP-статус: например, 400 / 503
  • Текст ошибки: вставьте полное сообщение об ошибке, включая (request id: ...)
  • Что уже пробовали: например, сменили модель, проверили Base URL, повторили запрос 2 раза
  • task_id (только для асинхронных видеозадач): ID задачи, возвращённый при отправке

Два важных момента: не отправляйте полный API-ключ; если в теле запроса или изображениях есть конфиденциальные данные, сначала обезличьте их, а потом отправляйте.


Что обновление документации Request ID меняет для разработчиков

Что это значит для разработчиков

  • Меньше лишней переписки при обращении в поддержку: сразу присылаете правильный ID, и поддержке не нужно ничего уточнять.
  • Пользователи SDK больше не получают пустые значения: явно описаны подводные камни _request_id и как получать его через with_raw_response.
  • Видеозадачи можно отследить: Request ID и ID задачи хранятся отдельно, так что есть основа для проверки задачи и списаний.

Что учитывать при чтении старой документации

На некоторых страницах с описанием возможностей API, новостных страницах и страницах о хранении ошибок x-request-id по-прежнему описан как объект, который «нужно записать для удобства диагностики». Если встречаете такую формулировку, ориентируйтесь на новую страницу Request ID. В шаблонах кода тоже замените x-request-id на x-shellapi-request-id.

Частые вопросы (FAQ)

Q1: Какой именно Request ID у APIYI?

Это `X-Shellapi-Request-Id` в заголовке ответа; он начинается с 14-значной временной метки UTC. При ошибке значение в конце сообщения об ошибке, в `(request id: …)`, совпадает с ним.

Q2: Безопасно ли передавать Request ID другим?

Да, безопасно. Согласно документации, Request ID — не ключ, его можно указывать в тикете, чате или на скриншоте. А вот полный API-ключ, начинающийся с `sk-`, передавать наружу нельзя.

Q3: Почему ID, который возвращает OpenAI SDK, пустой?

По умолчанию SDK в `_request_id` считывает x-request-id. Используйте `with_raw_response` или достаньте x-shellapi-request-id из заголовков ответа `APIStatusError`.

Q4: Как быстро проверить, что я получаю правильный Request ID?

1. Зарегистрируйтесь на APIYI apiyi.com и получите API-ключ — новым пользователям доступен бесплатный тестовый лимит.
2. Установите Base URL в `https://api.apiyi.com/v1` и отправьте минимальный запрос.
3. Выведите x-shellapi-request-id и убедитесь, что при каждом вызове вы получаете этот ID; страница логов позволяет проверить только то, дошёл ли вызов и было ли списание, но сам ID там не показывается.

Q5: Можно ли найти ошибку трёхмесячной давности?

Обычно нет. Логи хранятся за текущий и два предыдущих календарных месяца; для более старых записей придётся опираться на сохранённые вами Request ID и исходный текст ошибки.


APIYI Request ID: главное

  • Единственно верный ID: X-Shellapi-Request-Id, начинается с 14-значной метки времени UTC
  • Два способа получить: скопировать из сообщения об ошибке (message) или прочитать заголовок ответа в коде (логи подтверждают только вызов, ID в них не отображается)
  • Что часто путают: X-Request-Id, req_, chatcmpl-, resp_, UUID — всё это не подходит для обращения в поддержку
  • Для видео храните два значения: Request ID, указанный при отправке, и ID задачи — сохраняйте отдельно
  • Логи не дают 100% гарантии: на странице консоли ID не отображается; для запросов, которые шлюз отклонил сразу, может не быть даже записи — тогда приложите исходный текст ошибки и время
  • Проверка на практике: отправьте минимальный запрос через APIYI apiyi.com и убедитесь, что этот заголовок читается

Итог

В этом обновлении документации APIYI по поиску Request ID главное — три вещи:

  1. Ответ — в начале: Request ID — это X-Shellapi-Request-Id; то же значение есть в конце сообщения об ошибке.
  2. Исключение неправильных ID: таблица сопоставления показывает разницу между ID промежуточного слоя, upstream, телом ответа и ID задачи.
  3. Если ID не находится — есть план: для четырёх ситуаций указано, какие материалы приложить, плюс готовый шаблон заявки.

Рекомендую прямо сейчас изменить поле лога ошибок в коде на x-shellapi-request-id. Если возникнет проблема, сообщите поддержке ID и время вызова — бэкенд найдёт запись по ID, — а затем отправьте заявку с полным комплектом материалов.


📚 Справочные материалы

  1. Документация APIYI по диагностике Request ID (новая версия): фактическая основа этой статьи
  2. Ссылка: docs.apiyi.com/faq/request-id-troubleshooting
  3. Описание: содержит два способа получения, пояснения по логам консоли, таблицу соответствия ID, разъяснения по асинхронному видео и шаблон тикета

  4. Как долго хранятся логи: пояснения о сроке хранения логов

  5. Ссылка: docs.apiyi.com/faq/log-retention-policy
  6. Описание: помогает проверить, можно ли ещё найти записи об ошибках

Автор: техническая команда APIYI
Обмен опытом: свяжитесь с нами на главной странице сайта APIYI apiyi.com; при подаче тикета приложите X-Shellapi-Request-Id — это ускорит обработку

Похожие записи