Перейти до вмісту
v1.1 · ПрацюєREST · JSONUSD

Документація API

Асинхронні завдання, підписані вебхуки, сумісні з OpenAI кінцеві точки. Ти платиш за запуск, а невдалі завдання повертаються.

Базовий URLhttps://api.fcaai.ai/v1

Швидкий старт

  1. Створи ключОбліковий запис › Ключі розробника. Використовуй тестовий ключ, щоб відокремити розробку від робочого середовища; запуски оплачуються однаково: fcaai_test_ Запиши його в FCAAI_API_KEY; SDK та CLI читають ключ звідти.
  2. Встанови SDK або CLITypeScript для Node 18+, Deno, Bun і edge-середовищ, Python 3.9+ або термінал. curl встановлювати не потрібно. npm i @fcaai/sdkpip install fcaainpm i -g @fcaai/cli
  3. Запусти свою першу генераціюВиклик одразу повертає 202 з id завдання та його ціною. З { wait: true } SDK повертає результат, коли завдання завершено.
export FCAAI_API_KEY="fcaai_test_…"

# 1) queue a job → 202 { "id", "status": "queued", "price_usd", "eta_seconds" }
curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"fca/magic-pro","input":{"prompt":"glass villa on a pine ridge at blue hour","aspect_ratio":"16:9","resolution":"2k"}}'

# 2) long poll: holds up to 60 s, returns as soon as the job ends; repeat while queued/running
curl "https://api.fcaai.ai/v1/generations/$GEN_ID?wait=50" \
  -H "Authorization: Bearer $FCAAI_API_KEY"
# → "status": "succeeded", "output": [{ "url": "https://…", "kind": "image", … }]

Автентифікація

Надсилай свій ключ як bearer-токен із кожним запитом.

  • Ключі, що починаються з fcaai_live_, — для робочого середовища, а ключі, що починаються з fcaai_test_, — для розробки. Обидва оплачуються однаково; тестові ключі лише розділяють середовища.
  • Ключ показується один раз — коли ти його створюєш, а ми зберігаємо лише відбиток. Зберігай його у змінній середовища, наприклад FCAAI_API_KEY, і ніколи — в коді, що виконується у браузері чи застосунку.
  • Відсутній, хибний, відкликаний чи прострочений ключ повертає 401. Ключ без потрібної області доступу або використаний з IP поза списком дозволених повертає 403.
curl https://api.fcaai.ai/v1/models \
  -H "Authorization: Bearer $FCAAI_API_KEY"

Як повертаються результати

Кожна генерація — це завдання: queued → running → succeeded, failed або canceled. Невдалі й скасовані завдання повертаються.

{
  "id": "cmvusmtm300234pbo7l6ecl3f",
  "object": "generation",
  "model": "fca/magic-pro",
  "status": "queued",
  "price_usd": 0.03,
  "currency": "USD",
  "eta_seconds": 14,
  "output": null
}

Скасування генерації

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

  • Спершу прочитай cancellable у генерації: воно завжди true, поки вона в черзі, і зазвичай false після початку.
  • Скасування вже завершеної генерації повертає її без змін.
# can it still be cancelled?
curl https://api.fcaai.ai/v1/generations/$GEN_ID -H "Authorization: Bearer $FCAAI_API_KEY"
# → "status": "queued", "cancellable": true, …

curl -X POST https://api.fcaai.ai/v1/generations/$GEN_ID/cancel -H "Authorization: Bearer $FCAAI_API_KEY"
# → 200: the generation, "status": "canceled"
# → 409 "already_started": it finishes and is charged as usual

Використання й баланс

GET /v1/account/usage повертає генерації, збої й витрати в USD за днями та моделями. Охоплює останні 30 днів, якщо не передати from і to у форматі YYYY-MM-DD.

  • GET /v1/account/balance повертає твій доступний баланс у USD.
# per day and model; the last 30 days unless you pass from and to
curl "https://api.fcaai.ai/v1/account/usage?from=2026-10-01&to=2026-10-31" -H "Authorization: Bearer $FCAAI_API_KEY"

curl https://api.fcaai.ai/v1/account/balance -H "Authorization: Bearer $FCAAI_API_KEY"
Крок за кроком

Посібники

Покрокові рецепти для найпоширеніших завдань. У прикладах використано офіційні SDK; вкладка curl показує звичайний HTTP-запит.

Редагування зображення із зображеннями-референсами

Надішли фото для редагування й зображення-референси одним списком images, а тоді опиши зміну. Посилайся на зображення за порядком (зображення 1, зображення 2…).

  1. Завантаж локальні файли або використай будь-який публічний URL https.
  2. Зображення для редагування постав першим у images; решта — референси.
  3. Перевір constraints.max_input_images у відомостях про модель: там вказано, скільки зображень вона приймає.

Збережених персонажів, товари й місця з бібліотеки можна додати через element_ids (до 3); їхні зображення-референси прикріплюються на нашому боці.

curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/nano-banana-pro","input":{"prompt":"Put the armchair from image 2 next to the window. Keep the room, light and camera unchanged.","images":["https://example.com/room.jpg","https://example.com/armchair.jpg"],"resolution":"2k"}}'

# how many images this model takes
curl https://api.fcaai.ai/v1/models/google/nano-banana-pro -H "Authorization: Bearer $FCAAI_API_KEY"
# → "constraints": { "max_input_images": …, … }

Зображення у відео з початковим і кінцевим кадром

Відеомоделі приймають перший кадр у image і, якщо підтримують це, останній кадр у end_image. Кліп рухається від одного до іншого.

  1. Перевір модель: constraints.features.end_frame має бути true, а тривалість — вкладатися в constraints.duration.
  2. Надішли image, end_image, промпт і тривалість. Рухи камери — це звичайний текст промпту.
  3. Відео створюється кілька хвилин: чекай із довшим тайм-аутом або використай вебхук.

Моделі з features.reference мають ще й режим референсів: надішли reference_images замість кадрів і назви їх у промпті @Image1, @Image2. Його не можна поєднувати з image чи end_image.

# price with an end frame
curl "https://api.fcaai.ai/v1/models/kling/3.0-pro?duration=5&end_image=1" -H "Authorization: Bearer $FCAAI_API_KEY"

curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling/3.0-pro","input":{"prompt":"slow dolly in, morning light moves across the floor","image":"https://example.com/start.jpg","end_image":"https://example.com/end.jpg","duration":5}}'

Збільшення зображення

Збільшувачі приймають одне image і масштаб у tier. fca/upscale має два режими: Standard для фото (до 16x) і Sharp для рендерів, планів і тексту (до 4x).

  1. Дізнайся ціну для розміру свого джерела: ?tier=4x&source_width=…&source_height=….
  2. Надішли зображення й масштаб. "tier": "max" обирає найбільший масштаб, що підходить зображенню (результат до 64 МП).
  3. Новий розмір — у полі width / height результату.

Покращувачі, зміна освітлення, розширення, видалення тла й збільшення відео перелічено в GET /v1/models?type=upscale.

curl "https://api.fcaai.ai/v1/models/fca/upscale?tier=4x&source_width=1600&source_height=1000" -H "Authorization: Bearer $FCAAI_API_KEY"

curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"fca/upscale","input":{"image":"https://example.com/render.jpg","tier":"4x","extra":{"look":"sharp"}}}'

Запуск шаблону

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

  1. Отримай шаблон, щоб побачити його inputs (ключ, тип, обов’язковість, варіанти) та pricing.
  2. Запусти його з { "values": { key: value } }. Поля-зображення приймають URL https.
  3. Чекай на нього, як на будь-яке інше завдання. Хибне значення повертає 400 invalid_values з fields.

Багатокрокові шаблони (package) починають запуск шаблону з кількох кроків: використовуй templates.runPackage / run_package.

curl https://api.fcaai.ai/v1/templates -H "Authorization: Bearer $FCAAI_API_KEY"
curl https://api.fcaai.ai/v1/templates/$SLUG -H "Authorization: Bearer $FCAAI_API_KEY"     # inputs, pricing, options (models[].id → run "model")

curl https://api.fcaai.ai/v1/templates/$SLUG/run \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"values":{"photo":"https://example.com/room.jpg"}}'
# → 202: a generation (poll GET /v1/generations/{id}?wait=50)
#   multi-step templates return a template_run (GET /v1/templates/runs/{id})

Спершу дізнайся ціну й параметри моделі

Один безкоштовний виклик повертає все, що приймає модель, і точну ціну для твоїх налаштувань. Він використовує ту саму логіку цін, що й POST /v1/generations, тож розрахована ціна — це те, що ти заплатиш.

  1. Виклич GET /v1/models/{id} з налаштуваннями, які надсилатимеш: duration · resolution · quality · tier · count · audio=1 · images=2 · end_image=1 · reference_images=3.
  2. Прочитай ціну в estimate.price_usd і перевір availability перед запуском.
  3. Збудуй свою форму з options та constraints: співвідношення сторін, роздільності, тривалість, максимум результатів, максимум вхідних зображень і можливості.

Значення, якого модель не дозволяє, повертається в invalid_params — з полем і дозволеними значеннями.

curl "https://api.fcaai.ai/v1/models/google/veo-3.1?duration=8&resolution=1080p&audio=1&end_image=1" -H "Authorization: Bearer $FCAAI_API_KEY"
# → { "availability": "available",
#     "estimate": { "price_usd": …, "price_display": "$…", "currency": "USD" },
#     "options": { … }, "constraints": { … }, "input_schema": { … } }

curl "https://api.fcaai.ai/v1/models?type=video" -H "Authorization: Bearer $FCAAI_API_KEY"   # the whole catalog for your key

Завантаження файлів

Кожен вхід — це URL https. Публічні URL працюють як є; локальні файли спершу завантаж і використай url, який отримаєш у відповідь.

  1. До 50 МБ: один запит до POST /v1/uploads.
  2. До 2 ГБ: відкрий сесію, надішли частини по 8 МБ у будь-якому порядку (можна й паралельно), а тоді заверш її.
  3. Надішли sha256 під час відкриття сесії, щоб відновити перерване завантаження або пропустити файл, який уже збережено.

SDK та CLI самі ділять файл, надсилають по 3 частини одночасно й відновлюють завантаження за id сесії.

# ≤ 50 MB
curl https://api.fcaai.ai/v1/uploads -H "Authorization: Bearer $FCAAI_API_KEY" -F "[email protected]"
# → 201 { "id": "…", "object": "upload", "url": "https://…", "mime": "image/jpeg", "bytes": … }

# up to 2 GB: 1) start a session
curl https://api.fcaai.ai/v1/uploads/sessions \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"walkthrough.mp4","mime":"video/mp4","bytes":104857600}'
# 2) PUT each 8 MB chunk (any order, in parallel)
split -b 8388608 -d -a 4 walkthrough.mp4 part_
curl -X PUT https://api.fcaai.ai/v1/uploads/sessions/$SESSION/chunks/0 -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/octet-stream" --data-binary @part_0000
# 3) finish → { "upload": { "url": … } }
curl -X POST https://api.fcaai.ai/v1/uploads/sessions/$SESSION/complete -H "Authorization: Bearer $FCAAI_API_KEY"

Отримання результатів через вебхук

Замість опитування дозволь нам викликати твій сервер, коли завдання закінчується. Зареєструй URL для всього облікового запису або додай options.webhook_url до окремого запиту (його секрет повертається один раз як webhook_secret).

  1. Зареєструй через POST /v1/webhooks: свій URL https і потрібні події. secret показується лише раз, тож збережи його.
  2. Перевіряй кожну доставку: X-FCAAI-Signature: t=…,v1=… — це HMAC-SHA256 від t + "." + rawBody з твоїм секретом. Використовуй сире тіло запиту й відхиляй старі позначки часу.
  3. Швидко відповідай 2xx, а роботу виконуй потім. Невдалу доставку ми пробуємо загалом 5 разів: одразу, а потім через 30 с, 2 хв, 10 хв і 1 год. Кожна спроба є в GET /v1/webhooks/{id}/deliveries.

Подія може надійти більше одного разу; використовуй її id, щоб пропускати дублікати.

Події
generation.succeededgeneration.failedgeneration.canceledflow_run.succeededflow_run.failedflow_run.canceledtimeline.preview_readytimeline.donetimeline.failedapproval.requestedapproval.decided

Приймаються лише публічні адреси https, і адреса перевіряється знову під час кожної доставки.

curl https://api.fcaai.ai/v1/webhooks \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/fcaai-hook","events":["generation.succeeded","generation.failed"]}'
# → 201 { "id": "…", "events": [ … ], "secret": "whsec_…" }   (secret shown only here)

# or one event for one job: add to POST /v1/generations
#   "options": { "webhook_url": "https://example.com/fcaai-hook" }
# → the 202 response carries "webhook_secret" (shown only there)

# delivery log: the latest 50 attempts
curl https://api.fcaai.ai/v1/webhooks/$WEBHOOK_ID/deliveries -H "Authorization: Bearer $FCAAI_API_KEY"

Обробка помилок і проігнорованих налаштувань

Помилки повертаються як JSON зі сталим error.code, за яким можна розгалужувати логіку. Налаштування, яке не вдалося застосувати, не провалює завдання: воно потрапляє до ignored_fields.

  1. Перевір статус HTTP і error.code. Коли значення хибне, allowed перелічує дійсні.
  2. Повторюй 429 і 5xx після Retry-After — з тим самим Idempotency-Key, щоб нічого не списалося двічі. SDK роблять і те, і те за тебе.
  3. Прочитай ignored_fields у відповіді 202; кожен запис має field · reason · message.

Невдалі завдання повертаються автоматично. Якщо звичний маршрут моделі не працює, завдання саме переходить на запасний; 503 model_unavailable означає, що зараз немає вільного маршруту.

СтатусКодиЩо робити
400invalid_bodyinvalid_durationinvalid_aspect_ratiomodel_not_allowedПоле відсутнє або не дозволене для цієї моделі. Виправ запит; повторне надсилання без змін знову не вдасться.
401invalid_api_keyapi_key_revokedapi_key_expiredКлюч відсутній, хибний, відкликаний або прострочений.
402insufficient_balancekey_spend_cap_reachedБракує балансу, або ключ досяг місячного ліміту. Нічого не списано.
403insufficient_scopeip_not_allowedКлюч не має області доступу (див. required_scope), або IP запиту немає в списку дозволених.
404model_not_foundТакої моделі немає, або вона не відкрита для твого ключа.
429rate_limitedЗабагато запитів. Зачекай час, указаний у Retry-After.
503model_unavailableМодель зайнята або вимкнена. Повтори трохи згодом або обери іншу модель.
Причини в ignored_fields
unknown_field
Такого поля в цьому запиті немає; перевір написання.
not_supported_by_model
Дійсне поле, якого ця модель не приймає.
nearest_supported
Такого співвідношення сторін немає; використано найближче.
follows_input_image
Під час редагування ця модель зберігає розмір або співвідношення сторін вхідного зображення.
unpriced_extra
Додаткове налаштування, якого модель не визначає, вилучено.
import { Fcaai, FcaaiError } from '@fcaai/sdk'

type Ignored = { field: string; reason: string; message: string }
const fcaai = new Fcaai({ maxRetries: 2 }) // 429 / 5xx / network errors: retried with backoff, honoring Retry-After

try {
  const gen = await fcaai.generations.create({ model: 'google/veo-3.1', input: { prompt: 'waves at dusk, slow pan', duration: 6 } })
  const { ignored_fields = [] } = gen as unknown as { ignored_fields?: Ignored[] }
  for (const f of ignored_fields) console.warn(f.field + ' ignored (' + f.reason + '): ' + f.message)
} catch (e) {
  if (!(e instanceof FcaaiError)) throw e
  const allowed = (e.body as { error?: { allowed?: unknown[] } } | null)?.error?.allowed
  if (e.status === 400) console.error(e.code, e.message, allowed)   // fix the request; do not retry as is
  else if (e.status === 402) console.error('Top up, or raise the key cap:', e.message)
  else if (e.code === 'model_unavailable') console.error('Retry shortly or pick another model')
  else throw e
}

Сумісні з OpenAI кінцеві точки

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

  1. Встанови базовий URL https://api.fcaai.ai/v1 і використовуй свій ключ fcaai як ключ API.
  2. Чат: POST /v1/chat/completions з моделлю fca/chat. Потокова передача, інструменти й вивід JSON працюють як зазвичай.
  3. Зображення: POST /v1/images/generations чекає до 90 с і повертає data[].url. Якщо завданню потрібно більше часу, ти отримаєш 202 з fcaai.generation_id; стеж за ним через GET /v1/generations/{id}.

Для відео, аудіо, 3D, збільшення й усіх параметрів моделей використовуй POST /v1/generations.

curl https://api.fcaai.ai/v1/chat/completions \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"fca/chat","messages":[{"role":"user","content":"Write a one-line caption for a walnut side table."}]}'

curl https://api.fcaai.ai/v1/images/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/nano-banana-pro","prompt":"a paper plane on a wooden desk","size":"1536x1024"}'
# → { "created": …, "data": [{ "url": "https://…" }], "fcaai": { "generation_id": "…", "price_usd": … } }

Перепродаж власним клієнтам

Реселерські облікові записи можуть відкривати субакаунт для кожного клієнта, давати йому власні ключі й стежити за використанням кожного клієнта за оптовою ціною.

  1. Використовуй ключ керування з областю доступу reseller:manage. Клієнтські ключі її ніколи не отримують.
  2. Створи клієнта через POST /v1/reseller/subtenants, а тоді його ключ через POST /v1/reseller/subtenants/{id}/keys. Повний ключ показується лише раз.
  3. Стеж за використанням і маржею кожного клієнта через GET /v1/reseller/usage. Щоб позначати власних кінцевих користувачів у генераціях, надсилай external_user_id.

Ключі без реселерської області доступу отримують 403 на цих кінцевих точках.

curl https://api.fcaai.ai/v1/reseller/subtenants \
  -H "Authorization: Bearer $FCAAI_RESELLER_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Acme Studio","plan":"pro","retail_markup":1.5}'

curl https://api.fcaai.ai/v1/reseller/subtenants/$CUSTOMER_ID/keys \
  -H "Authorization: Bearer $FCAAI_RESELLER_KEY" -H "Content-Type: application/json" \
  -d '{"name":"production","mode":"live"}'

curl "https://api.fcaai.ai/v1/reseller/usage?from=2026-10-01" -H "Authorization: Bearer $FCAAI_RESELLER_KEY"
Довідник

Що можна створити

Кінцевих точок: 69. Кожна описана в повному довіднику з прикладами на curl, TypeScript і Python.

GET/v1/style-kitsСтильові набори
GET/v1/elementsЕлементи
POST/v1/video-editsРедагування відео: обрізання, з’єднання, зображення, текст і логотип, звукова доріжка (асинхронно, безкоштовно)
GET/v1/generationsСписок генерацій
POST/v1/generationsСтворити генерацію (асинхронно)
GET/v1/generations/{id}Отримати генерацію (тривале опитування з wait)
POST/v1/generations/{id}/cancelСкасувати (зарезервований баланс звільняється)

Ціни

Долари за запуск — з того самого балансу, що й твій план. Це актуальні ціни за типових налаштувань; на сторінці кожної моделі наведено всі ціни за роздільністю й тривалістю.

МодельЗавданняAPI (USD)
Nano Banana ProЗображення · зображення · 2K$0.13
GPT Image 2.5 FlareЗображення · зображення · 2K$0.055
FCA Magic ProЗображення · зображення · 2K$0.03
Kling 3.0 ProВідео · за секунду · 1080p$0.11
FCA Magic V3Відео · за секунду · 1080p$0.017
ElevenLabs v3Аудіо · кліп$0.024
Розрахунок ціни безкоштовнийНевдалі запуски повертаютьсяАвтопоповнення типово вимкненоВ API немає безлімітного плану

Ключі й ліміти

Кожен ключ має власну область доступу, частоту запитів і ліміт витрат. Заголовки відповіді показують, скільки лишилося.

120 / хвТипова частота запитів на ключ. X-RateLimit-*
2Завдань, що виконуються одночасно, на ключ (можна збільшити).
Місячний лімітУ USD; коли його досягнуто, запити отримують 402 key_spend_cap_reached
Область доступуЗображення, відео, аудіо, 3D, збільшення й LLM вмикаються поодинці.
Список дозволених IPПрив’яжи ключ до IP-адрес своїх серверів.
Idempotency-KeyПовтор із тим самим ключем ніколи не списує двічі.

SDK та інструменти

Офіційні SDK для TypeScript і Python та CLI. SDK безпечно повторюють запити з ключами ідемпотентності, чекають на результати, завантажують великі файли частинами й перевіряють підписи вебхуків.

TypeScriptnpmjs.com (відкривається в новій вкладці)Node 18+, Deno, Bun і edge-середовища
Pythonpypi.org (відкривається в новій вкладці)Python 3.9+, лише стандартна бібліотека
CLInpmjs.com (відкривається в новій вкладці)Кожна модель — із твого термінала
MCPПідключи своїх ШІ-агентів до тих самих моделей і того самого балансу.
Кожна кінцева точка, поле й код помилки

Інтерактивний довідник: пробуй запити у браузері й копіюй приклади коду.

Повний довідник API(відкривається в новій вкладці)