slen.ai
Начать

Отправьте первый запрос

PHP

Запустите опубликованный флоу из своего приложения через SDK и прочитайте, что он ответил.

6 мин чтения

Эта страница ведёт от API-ключа до первого ответа флоу. Ваше приложение называет операцию, Slen выполняет привязанный к ней флоу, а SDK возвращает то, что флоу ответил.

Что понадобится

  • API-ключ с разрешением gateway:write. Выпустите его на странице Ключи и доступ — по шагам это описано в статье Управление API-ключами.

  • Опубликованный флоу. Флоу собирают и публикуют на странице AI-флоу — публикация по шагам описана в статье Публикация, версии и откат.

  • Код операции, привязанный к флоу. Откройте флоу, затем его вкладку Настройки. В блоке Привязка операции введите код в поле Код операции и нажмите Сохранить привязку. В примерах этой страницы используется код generate_email.

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

Отправить запрос

1. Установите SDK

Composer
composer require slen/sdk guzzlehttp/guzzle

Запрос этой страницы можно отправить и без SDK. Тот же запрос по HTTP приведён после шагов. Что нужно каждому SDK, говорит статья Установка.

Положите ключ туда, откуда приложение читает свои секреты. Примеры этого справочника читают его из переменной окружения SLEN_API_KEY.

Terminal
export SLEN_API_KEY="sl_live_…"

2. Создайте клиент

Клиент принимает API-ключ, и больше ничего не нужно: он обращается к API Slen. Другие его опции перечисляет статья Конфигурация.

PHP
use Slen\Sdk\SlenConfig;
use Slen\Sdk\SlenSdk;

$slen = SlenSdk::create(new SlenConfig(apiKey: (string) getenv('SLEN_API_KEY')));

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

3. Выполните операцию

PHP
use Slen\Sdk\Modules\Operations\Options\ExecuteOptions;

$execution = $slen->operations()->execute(
    'generate_email',
    ['messages' => [['role' => 'user', 'content' => 'Write a short follow-up email.']]],
    new ExecuteOptions(idempotencyKey: 'order-42:email'),
);

  • Первый аргумент — код операции, привязанный к флоу. Это не название флоу.

  • Второй аргумент — вход флоу. Флоу с узлом AI-модель нужен непустой input.messages.

  • Ключ идемпотентности называет единицу работы, здесь — письмо по заказу 42. Запрос, повторённый с тем же ключом и тем же телом, не выполняет флоу второй раз. Ответом на него будет выполнение, которое начал первый запрос, — в том состоянии, в каком оно находится в этот момент, — и replayed в ответе равно true.

Предупреждение:

Без вашего собственного ключа SDK создаёт новый ключ для каждого вызова. Тогда запрос, который приложение отправило ещё раз, — это второе выполнение и вторая трата.

4. Прочитайте ответ

Вызов возвращает выполнение. Когда его статус — completed, в output лежит то, что вернул флоу. cost.estimated — сколько, как ожидалось, будут стоить его вызовы моделей. Сколько они стоили, cost.actual, приходит после ответа — когда, говорит статья Отправить запрос.

PHP
if ($execution->isCompleted()) {
    echo $execution->output['content'], PHP_EOL;
}

Тот же запрос по HTTP

SDK отправляет один запрос. Вот этот запрос и ответ на него.

Terminal
curl https://api.slen.ai/api/v1/operations/execute \
  -H "Authorization: Bearer $SLEN_API_KEY" \
  -H "Idempotency-Key: order-42:email" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "generate_email",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "Write a short follow-up email."
        }
      ]
    }
  }'
200 OK
{
  "data": {
    "execution_id": "74438200973594700",
    "status": "completed",
    "operation": "generate_email",
    "output": {
      "model": "gpt-4o",
      "content": "Hi Ada, just checking in on the proposal I sent last week.",
      "finish_reason": "stop",
      "tool_calls": null,
      "usage": {
        "input_tokens": 14,
        "output_tokens": 16,
        "cached_input_tokens": 0
      }
    },
    "error": null,
    "error_code": null,
    "error_message": null,
    "cost": {
      "estimated": "0.00412500",
      "actual": null
    },
    "cache": {
      "hit": false,
      "cached_at": null
    },
    "replayed": false,
    "waiting_on": null,
    "trace_url": "/v1/executions/74438200973594700"
  }
}

Что говорит ответ

Статус выполнения говорит, чем закончился запрос.

СтатусЧто он значит
completedФлоу дошёл до Вернуть ответ. В output лежит его ответ
rejectedФлоу дошёл до Отклонить запрос, или отказ по пути закрыл выполнение. error_code и error_message говорят почему
failedВыполнение закрыла ошибка по пути. error_code называет причину и равен null, когда у API нет кода для этой ошибки
uncertainНеизвестно, чем закончился вызов модели: провайдер не ответил вовремя или его нельзя было спросить о вызове, который он выполняет в фоне
waitingФлоу остановился на узле, который ждёт, и продолжится позже
queuedЗапрос отправлен в асинхронном режиме, и флоу ещё не начался
runningФлоу выполняется прямо сейчас. Этот статус читает повторный запрос, пришедший во время выполнения

waiting, queued и running — не окончательные статусы. Как дождаться результата, показывает статья Асинхронные запуски и ожидание.

На запрос, который отклонён или упал по пути, не отвечают выполнением. API отвечает ошибкой, и SDK её выбрасывает — как её поймать, показывает статья Обработка ошибок. На первом запросе часто встречаются две ошибки.

  • 404 с кодом flow_not_found — к коду операции не привязан флоу, у флоу нет опубликованной версии или флоу в архиве.

  • 422 с кодом invalid_flow_input — флоу вызывает модель, а во входе нет messages.

Ошибка, пришедшая после начала выполнения, оставляет это выполнение закрытым, и ключ остаётся за ним. invalid_flow_input — такая ошибка, а flow_not_found — нет.

  • На повтор того же запроса под этим ключом отвечает выполнение, а не снова ошибка. Его статус говорит, чем оно закончилось, — failed после invalid_flow_input, — а error_code называет причину.

  • Тот же ключ с другим телом отклоняется: 409 с кодом idempotency_conflict. Отправьте исправленный запрос под новым ключом.

Найти выполнение в консоли

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

trace_url в ответе — путь того же выполнения в API.

Что читать дальше