Общие соглашения

Эта страница описывает общие правила вызова endpoints API AGTCloud. Конкретные поля, статусы и структуры ответов определяются соответствующей страницей справочника API.

Адрес API и Base URL

На этой странице адрес API — https://api.agtcloud.cn, а Base URL для SDK, совместимого с OpenAI, — https://api.agtcloud.cn/v1.

Аутентификация

Большинство защищённых API используют Bearer-ключ API:

Authorization: Bearer your-api-key

Anthropic Messages использует собственные Header аутентификации и требует версию API:

x-api-key: your-api-key
anthropic-version: 2023-06-01

Необязательные Header, например anthropic-beta, и требования других протоколов определяются страницей соответствующего Endpoint.

Создавайте и управляйте токенами в API Keys. При вызове передавайте только ключ API, а не пароль консоли, Cookie, токен администратора или ключ поставщика.

Минимальный запрос Chat Completions:

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  --request POST \
  --header 'Authorization: Bearer your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Здравствуйте"
      }
    ]
  }'

Создание, ротация и хранение ключей в производственной среде описаны в Ключе API, Base URL и аутентификации.

Где задаются параметры запроса

На странице endpoint поля разделены по расположению параметра:

Параметры Path сначала следует URL-кодировать. Неиспользуемые необязательные параметры опускайте, а не заменяйте все их значения пустыми строками.

Content-Type и форматы данных

Для Multipart не задавайте boundary вручную; браузер, SDK или HTTP-клиент должен сформировать полный Content-Type по содержимому формы.

ID модели

MODEL_ID в примерах справочника — заполнитель. Замените его ID модели, доступной текущему ключу API. Найти модель можно в каталоге моделей или получить список, возвращаемый этим ключом, введя его в Try It.

Модель, протокол и поставщик — разные понятия:

• ID модели определяет целевую модель запроса.
• Endpoint определяет протокол и структуру сообщений клиента.
• Одна модель может предоставлять несколько протоколов или поддерживать лишь часть их полей.

Разбор ответа

При обработке ответа рекомендуется следующий порядок:

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

SSE передаёт несколько событий или блоков данных в одном HTTP-ответе. Клиент должен читать содержимое постепенно, а не ждать закрытия соединения и разбирать весь ответ как один JSON-объект.

• Определяйте конечное событие или маркер по описанию endpoint.
• Обрабатывайте приращения содержимого, вызовы инструментов, Usage и ошибки отдельно.
• При обрыве сети не считайте уже полученное содержимое полным результатом.
• Структуры потоковых событий различаются между протоколами; используйте определения текущего endpoint.

Асинхронные задачи

API видео, Midjourney и другие обычно сначала возвращают идентификатор задачи, а затем позволяют получать прогресс и результат через запрос статуса:

Отправить задачу → Сохранить ID задачи → Запросить статус → Определить конечное состояние → Прочитать результат

Имя поля ID задачи, значения статусов и путь запроса определяются конкретным протоколом. Не смешивайте id, task_id, video_id или значения статусов разных API.

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

Статусы HTTP и повторные попытки

Общие рекомендации ниже; конкретная структура ошибки определяется фактическим ответом endpoint:

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

Полные шаги диагностики приведены в Устранении неполадок.

Usage, время и расширенные поля

• Наличие и имена полей Usage зависят от протокола и модели; клиент должен допускать пустые или отсутствующие значения.
• Время может передаваться в секундах Unix, миллисекундах Unix или строкой; разбирайте по Schema endpoint.
• Расширения поставщика обычно применимы лишь к некоторым моделям, а не являются общими возможностями всех моделей.
• Клиент должен допускать новые некритичные поля ответа, чтобы добавление совместимых полей платформой не нарушало весь разбор.

Безопасность и журналы

• Постоянные ключи API храните на доверенном сервере или в системе управления секретами; не встраивайте их в производственный frontend, настольные или мобильные клиенты.
• Try It предназначен только для временной браузерной отладки, инициированной клиентом; не используйте постоянный производственный ключ на общих устройствах.
• Не записывайте ключ в публичные репозитории, снимки экрана, журналы или обращения в поддержку.
• Обезличивайте Prompt, адреса файлов, сведения об аккаунте и чувствительные данные запросов и ответов в диагностических материалах.
• Своевременно отключайте или удаляйте неиспользуемые либо предположительно скомпрометированные ключи и обновляйте использующие их сервисы.

Далее: Справочник API · Быстрый старт · Устранение неполадок