API генерації через x402: оплата за виклик без акаунта

x402 — це відкритий платіжний протокол, який перетворює давно забутий HTTP-код 402 на повноцінний пейвол: сервер відповідає на запит статусом 402 Payment Required зі структурованими умовами оплати, клієнт підписує дозвіл на переказ у стейблкоїнах, повторює запит і отримує готовий результат. Без створення акаунта, без API-ключів і без щомісячних підписок. Coinbase передала цей протокол до Linux Foundation у квітні 2026 року, і на момент початку операційної діяльності x402 Foundation до неї увійшли 40 організацій, серед яких AWS, Google, Stripe, Visa та Mastercard. Це більше не експеримент для вузького кола.

Коротка відповідь: ендпоінт x402 сервісу BananaBanana розташований за адресою https://bananabanana.pro/api/x402. Надішліть POST-запит із тілом { "tool": "...", "arguments": {...} }, отримайте відповідь 402 з точною вартістю для цих параметрів, сплатіть її в USDC на мережі Base і повторіть запит. Зображення коштують від $0.03, відео — від $0.30, синтез мовлення — $0.01 за кожні 200 символів. Оплата за зображення та мовлення списується лише за умови успішного створення файлу.

Останнє речення — саме та деталь, яку часто оминають в описах x402, тому ми розглянемо її детально. Списати оплату нескладно; не списувати кошти за невдалі виклики — ось де архітектурне рішення стає по-справжньому важливим.

Як насправді відбувається оплата

Усього чотири кроки, причому три з них ваш HTTP-клієнт виконує повністю автоматично:

1. Ваш агент надсилає стандартний POST-запит із JSON без платіжних заголовків.
2. Сервер повертає 402 з масивом accepts. Вимога платежу містить суму в неподільних одиницях (atomic units), адресу одержувача, контракт USDC, мережу та термін дії.
3. Клієнт підписує дозвіл на переказ за стандартом EIP-3009 на точну суму та кодує його в Base64 у заголовку X-PAYMENT.
4. Той самий запит надсилається повторно, тепер із заголовком. Сервер передає підпис фасилітатору для перевірки, виконує генерацію, а потім звертається до фасилітатора для проведення ончейн-розрахунку.

Підпис не є безпосередньо транзакцією в блокчейні. Це офчейн-дозвіл, який перетворюється на реальний переказ лише після передачі в мережу. Це уможливлює двоетапну схему: спочатку валідація, потім генерація і наприкінці — розрахунок.

Практична деталь: специфікація v2 перейменовує заголовки на PAYMENT-SIGNATURE та PAYMENT-RESPONSE, проте більшість чинних клієнтів усе ще використовують X-PAYMENT, і ми його повністю підтримуємо. Якщо ви працюєте через офіційний TypeScript SDK, ця різниця для вас непомітна.

Скільки коштує один виклик

Ціни розраховуються за генерацію та повідомляються до того, як ви щось підписуєте. Точна сума залежить від параметрів (зображення 4K коштує дорожче за 1K), тому відповідь 402 оцінює саме ваш конкретний запит.

Трисекундний ролик в Omni зі звуком коштує $0.30. Це найдоступніший варіант справжнього відеогенератора в переліку. Veo забезпечує вищу деталізацію, але для 8-секундного відео в 1080p з аудіо вартість помітно зростає, що не завжди потрібно для початкового драфту.

Актуальні тарифи можна перевірити напряму: GET https://bananabanana.pro/api/x402 безкоштовно повертає повний каталог без потреби в оплаті.

Дві взаємодії: повний цикл

Ось наочний приклад роботи через curl, за винятком етапу підписання (цю частину виконує ваша клієнтська бібліотека x402):

# 1. Запит розрахунку вартості. Без платіжного заголовка: отримання ціни.
curl -s -X POST https://bananabanana.pro/api/x402 \
  -H 'Content-Type: application/json' \
  -d '{"tool":"generate_image","arguments":{"prompt":"a paper boat on still water at dawn","model":"nano-banana-pro","resolution":"2048"}}'

{
  "x402Version": 1,
  "error": "Payment required: $0.11 for generate_image.",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "110000",
    "resource": "https://bananabanana.pro/api/x402",
    "payTo": "0x7c0e9abd1c48380e27ab5bfced1be54f23ce773f",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

Підпишіть зазначені параметри, надішліть запит із заголовком, і друга відповідь надасть згенерований файл:

{
  "paid_usd": 0.11,
  "result": {
    "status": "completed",
    "images": [{ "url": "https://bananabanana.pro/api/files/..." }]
  }
}

Дві суттєві деталі для тих, хто розробляє сервери x402: значення maxAmountRequired вказується в неподільних одиницях. Оскільки USDC має 6 знаків після коми, сума $0.11 стає 110000. Крім того, extra.name має точно відповідати результату виклику методу name() контракту USDC (у Base mainnet це USD Coin, а в Base Sepolia — USDC), оскільки це поле використовується для обчислення domain separator в EIP-712. За наявності розбіжностей перевірка підпису зазнає невдачі без чіткого повідомлення про причину.

Особливість відео: попередня оплата та токени повернення

Генерація зображень і мовлення вкладається в часові рамки одного HTTP-запиту (перевірка → генерація → розрахунок). Списання коштів відбувається лише в разі створення готового файлу. Якщо запит відхилено фільтрами безпеки або стався таймаут, підпис не надсилається до блокчейну і витрат не виникає.

З відео процес влаштований інакше: рендеринг у Veo або Omni триває від однієї до десяти хвилин, утримувати HTTP-з'єднання неможливо, а запущений на стороні Google процес не підлягає скасуванню (їхній метод interactions.cancel повертає 501 UNIMPLEMENTED). Тому для відео розрахунок здійснюється на старті, клієнт отримує job_id, а результат опитується через безкоштовний ендпоінт.

Що відбувається, якщо вже оплачений відеоролик не пройшов безпекову перевірку?

Ви отримуєте токен повернення (refund token) на повну суму у форматі bb_rf_…, дійсний протягом 90 днів, який можна передати в параметрі refund_token під час наступного виклику. Якщо ролик за $1.30 було заблоковано фільтром, наступний запит коштуватиме на $1.30 менше. Якщо вартість нового завдання менша за номінал токена, залишок повертається у вигляді нового токена.

Це не є поверненням USDC у блокчейні, і ми відкрито про це зазначаємо. Наш сервер не зберігає приватних ключів і не має можливості ініціювати вихідні транзакції — лише приймати або відхиляти вхідні платежі. З точки зору безпеки сервісу x402 відсутність приватних ключів на сервері є значною захисною перевагою.

Цей ролик створено через описаний ендпоінт за $0.30: модель Gemini Omni Flash, тривалість 3 секунди, промпт — неперервний план чорнил, що розчиняються у воді в скляному резервуарі з м'яким боковим освітленням і низьким гулом приміщення. Аудіо синтезовано безпосередньо моделлю.

Як агент знаходить ендпоінт

Якщо агент заздалегідь знає точну адресу, механізм виявлення не потрібен. Для інших агентів сервіс публікує маніфест за адресою /.well-known/x402 (а також /.well-known/x402.json).

Маніфест описує кожен інструмент як окремий ресурс із платіжними вимогами, ідентифікатором мережі за стандартом CAIP-2, адресою отримувача та фасилітатором. Блок accepts у маніфесті містить мінімальну вартість інструмента замість максимальної, щоб захистити агентів від випадкової надмірної сплати під час запиту каталогу.

Каталоги агентів також сканують ендпоінти порожніми POST-запитами. Наш сервер відповідає на них статусом 402 із підказкою щодо виклику інструментів.

Що обрати: x402 чи звичайний акаунт?

Обидва способи ведуть до однакових генеративних моделей. Обирайте відповідно до архітектури вашого агента.

Бонус на поповнення є вагомою перевагою: депозит у $100 з промокодом зараховує $120 на баланс (фактична знижка 17%), чого в x402 немає через відсутність акаунтів. З іншого боку, автономному агенту з гаманцем не потрібен email, і він може згенерувати контент за один цикл запиту.

Якщо вам зручніше працювати через акаунт, наш MCP-сервер підтримує Claude Code, Cursor та VS Code, а генератор доступний безпосередньо у браузері.

Часті запитання

Чи потрібен акаунт Coinbase для оплати?

Ні. Підходить будь-який EVM-гаманець із токенами USDC на мережі Base. Розрахунок проводить фасилітатор, реєструватися в нього окремо також не потрібно.

Що відбувається, якщо генерацію заблоковано фільтром безпеки?

Для зображень і мовлення кошти не списуються: розрахунок відбувається лише після створення файлу. Для відео надається токен повернення на повну суму для використання в наступних запитах.

Які мережі та токени підтримуються?

USDC в основній мережі Base (Base mainnet), схема exact. Маніфест на /.well-known/x402 містить CAIP-2 chain id та адресу контракту токена.

Чи можна відредагувати відео, створене через x402?

Через x402 — ні. Редагування прив'язане до історії завдань в акаунті (edit_video в MCP). Через x402 завжди можна створити нове відео з нуля.

Скільки діє запропонована ціна?

Вікно для підписання за замовчуванням становить 300 секунд (maxTimeoutSeconds). Базові тарифи відповідають цінам на сайті та залишаються стабільними.

Спробуйте згенерувати зображення за $0.03 на робочому ендпоінті. Якщо ваш клієнт вміє підписувати авторизацію EIP-3009, від отримання файлу вас відділяють лише чотири рядки коду.