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.

Що читати далі