fal-ai

name: fal-ai description: Генерирует изображения, видео, аудио через fal.ai API. Text-to-image — только nano-banana-2 (дефолт) или openai/gpt-image-2 (сложный текст на картинке). Видео/аудио/LLM — Kling, Veo, Sora, ElevenLabs, Kokoro, any-llm. Вызывай когда нужна генерация, удаление фона, апскейл, TTS, или когда упоминается fal.ai / FAL_KEY / nano-banana / gpt-image / kling. Включает reverse-prompt методологию — читай references/prompt-engineering.md перед любой генерацией.

fal.ai — генерация через API

Политика по моделям (см. global/rules.md): Text-to-image — разрешены ТОЛЬКО fal-ai/nano-banana-2 (по умолчанию) и openai/gpt-image-2 (для сложного текста / типографики на картинке). Никакие другие t2i (Flux, Ideogram, Recraft, Seedream, Qwen, Imagen, SDXL, Nano Banana Pro и т.п.) не используются. Img2img / inpainting / outpainting — через edit-эндпойнты тех же двух моделей.

Промпт-инжиниринг (обязательно перед генерацией)

Всегда читай references/prompt-engineering.md — там полная методология:

• Структура SLCT (Subject / Look / Camera / Technical)
• Reverse-prompt: анализ референс-изображения → разбор на составляющие → написание точного промпта
• Итеративный цикл улучшения
• Модельно-специфичные паттерны (nano-banana-2, gpt-image-2, kling, veo)
• Шаблоны для SMM: продукт, портрет, архитектура, видео
• Анти-паттерны и техники усиления

Кратко: пиши как режиссёр, а не как тег-суп. Конкретный субъект → конкретный свет → конкретная камера → стиль.

Конфигурация

API-ключ: .env в корне репо → FAL_KEY=...

Установка:

npm install @fal-ai/client

Импорт (именованный, не default):

import { fal } from "@fal-ai/client";
fal.config({ credentials: process.env.FAL_KEY });

Загрузить ключ в Bash-скрипт:

export $(grep -v '^#' .env | xargs)

Два метода вызова

⚠️ queue.fal.run может таймаутиться в некоторых сетях. Для изображений всегда используй fal.run().

Загрузка локальных файлов

import { fal } from "@fal-ai/client";
import fs from "fs";

const buf = fs.readFileSync("photo.jpg");
const imageUrl = await fal.storage.upload(
  new Blob([buf], { type: "image/jpeg" }),
  { contentType: "image/jpeg" }
);
// imageUrl — временный URL для передачи в модели

Скачать результат

import https from "https";
import fs from "fs";

async function download(url, dest) {
  fs.mkdirSync(require("path").dirname(dest), { recursive: true });
  return new Promise((resolve, reject) => {
    const file = fs.createWriteStream(dest);
    https.get(url, r => {
      r.pipe(file);
      file.on("finish", () => { file.close(); resolve(dest); });
    }).on("error", reject);
  });
}

ИЗОБРАЖЕНИЯ

Разрешены ровно две модели:

Любая другая t2i-модель — нарушение политики (global/rules.md).

Designer-агент: только node tools/generate-image.mjs ... [--model=nano-banana-2|gpt-image-2] [--quality=low|medium|high] — никаких кастомных скриптов, прямых fal.run, node -e, или самописных .mjs. Обёртка грузит .env, ставит таймаут и считает spend — без неё легко получить молчаливый hang.

Другие агенты (analytics и т.п.): прямые fal.run допустимы при условии ручного таймаута.

Прокси / ECONNRESET под VPN: по умолчанию тулзы ходят в fal.ai напрямую — HTTPS_PROXY не нужен. Но если оператор сидит под VPN с локальным прокси (типично 127.0.0.1:10809), прямые запросы режутся и валятся с ECONNRESET на аплоадах. Лечение: в .env добавить FAL_PROXY=http://127.0.0.1:10809 — тулзы поднимут undici ProxyAgent и пустят трафик через прокси (Node fetch сам env-прокси НЕ читает). Все fal-вызовы идут через tools/lib/fal-meter.mjs, который ещё и ретраит сетевые обрывы (3 попытки; TIMEOUT не ретраится). Полный разбор и диагностика — docs/fal-troubleshooting.md. Тинипрокси 5.2.66.188:8888 — только для серверных процессов (исторический OpenClaw, выкл. 16.05.2026).

nano-banana-2 (по умолчанию)

Model ID: fal-ai/nano-banana-2 | Gemini-based, 4K, поддерживает web search и до 14 референс-изображений.

Вывод:

{
  "images": [{ "url": "...", "width": 1024, "height": 1024, "content_type": "image/png" }],
  "description": "Описание сгенерированного изображения"
}

Пример:

const result = await fal.run("fal-ai/nano-banana-2", {
  input: {
    prompt: "cinematic photo of a red fox on snowy hill, golden hour",
    aspect_ratio: "16:9",
    resolution: "2K",
    output_format: "jpeg",
  },
});
const url = result.data.images[0].url;

gpt-image-2 (только для сложного текста)

Model ID: openai/gpt-image-2 | OpenAI, рендерит текст с пиксельной точностью, поддерживает мульти-язык, плотную типографику, до 4K.

Берём её только когда:

• На картинке должна быть длинная разборчивая надпись (заголовок-плакат, цитата, текст на упаковке, инфографика с цифрами/подписями)
• Несколько языков на одном изображении
• Художественная типографика, где nano-banana-2 ломает буквы

Для всего остального → nano-banana-2 дешевле в 2–10 раз и достаточно.

Пример:

const result = await fal.run("openai/gpt-image-2", {
  input: {
    prompt: "vintage travel poster reading 'SUMMER IN LISBON' in bold serif, terracotta and cream palette, art deco border",
    image_size: "portrait_4_3",
    quality: "high",
    output_format: "jpeg",
  },
});
const url = result.data.images[0].url;

Img2img / inpainting (если нужно править существующее с текстом): openai/gpt-image-2/edit — те же входы + image_url и опциональный mask_url. Это единственный разрешённый img2img/inpainting эндпойнт в проекте.

УДАЛЕНИЕ ФОНА

Пример (BRIA RMBG 2.0):

const buf = fs.readFileSync("photo.jpg");
const imageUrl = await fal.storage.upload(new Blob([buf], { type: "image/jpeg" }));

const result = await fal.subscribe("fal-ai/bria/background/remove", {
  input: { image_url: imageUrl },
  logs: true,
  onQueueUpdate: (u) => u.logs?.forEach(l => console.log("[fal]", l.message)),
});
// result.data.image.url — PNG с прозрачным фоном

АПСКЕЙЛ

Пример (SeedVR2):

const imageUrl = await fal.storage.upload(...);

const result = await fal.subscribe("fal-ai/seedvr/upscale/image", {
  input: {
    image_url: imageUrl,
    upscale_factor: 2,   // или upscale_mode: "target", target_resolution: "2160p"
    output_format: "jpg",
  },
  logs: true,
  onQueueUpdate: (u) => u.logs?.forEach(l => console.log("[fal]", l.message)),
});
// result.data.image.url

ВИДЕО: Text-to-Video

Пример (Kling 2.5 Turbo — оптимальный):

const result = await fal.subscribe("fal-ai/kling-video/v2.5-turbo/pro/text-to-video", {
  input: {
    prompt: "cinematic drone shot over city at sunset, golden hour, 4K",
    duration: "5",        // "5" | "10"
    aspect_ratio: "16:9", // "16:9" | "9:16" | "1:1"
  },
  logs: true,
  onQueueUpdate: (u) => {
    if (u.status === "IN_PROGRESS") u.logs?.forEach(l => console.log("[fal]", l.message));
  },
});
const videoUrl = result.data.video.url;

ВИДЕО: Image-to-Video

Пример (Kling 2.5 Turbo i2v):

const imgUrl = await fal.storage.upload(new Blob([fs.readFileSync("img.jpg")], { type: "image/jpeg" }));

const result = await fal.subscribe("fal-ai/kling-video/v2.5-turbo/pro/image-to-video", {
  input: {
    image_url: imgUrl,
    prompt: "gentle breeze, subtle camera movement",
    duration: "5",
    aspect_ratio: "16:9",
  },
  logs: true,
  onQueueUpdate: (u) => u.logs?.forEach(l => console.log("[fal]", l.message)),
});
const videoUrl = result.data.video.url;

АУДИО / TTS

Пример (ElevenLabs):

const result = await fal.subscribe("fal-ai/elevenlabs/tts/eleven-v3", {
  input: {
    text: "Привет, это тестовый текст",
    voice_id: "21m00Tcm4TlvDq8ikWAM",  // Rachel
    model_id: "eleven_v3",
  },
  logs: true,
  onQueueUpdate: (u) => u.logs?.forEach(l => console.log("[fal]", l.message)),
});
const audioUrl = result.data.audio.url;

Пример (Kokoro — дёшево):

const result = await fal.run("fal-ai/kokoro/american-english", {
  input: {
    text: "Hello, this is a test.",
    voice: "af_heart",  // american female heart
  },
});
const audioUrl = result.data.audio.url;

LLM через fal.ai (any-llm)

Model ID: fal-ai/any-llm

Единый gateway для всех LLM моделей. Поддерживаемые модели:

Пример:

const result = await fal.run("fal-ai/any-llm", {
  input: {
    model: "google/gemini-2.5-flash",
    prompt: "Напиши краткое описание для изображения заката",
  },
});
console.log(result.data.output);

Обработка ошибок

try {
  const result = await fal.run("fal-ai/nano-banana-2", { input: { prompt } });
  return result.data;
} catch (err) {
  if (err.status === 401) throw new Error("Неверный FAL_KEY");
  if (err.status === 422) throw new Error(`Validation: ${JSON.stringify(err.body)}`);
  throw err;
}

Быстрые рецепты

Изображение:     fal.run("fal-ai/nano-banana-2", { input: { prompt, aspect_ratio, resolution } })
Картинка с тек.: fal.run("openai/gpt-image-2",    { input: { prompt, image_size: "portrait_4_3", quality: "high" } })
T2V баланс:      fal.subscribe("fal-ai/kling-video/v2.5-turbo/pro/text-to-video", { input: { prompt, duration: "5", aspect_ratio: "16:9" } })
I2V:             fal.subscribe("fal-ai/kling-video/v2.5-turbo/pro/image-to-video", { input: { image_url, prompt, duration: "5" } })
Фон убрать:      fal.subscribe("fal-ai/bria/background/remove", { input: { image_url } })
Апскейл:         fal.subscribe("fal-ai/seedvr/upscale/image", { input: { image_url, upscale_factor: 2 } })
TTS:             fal.run("fal-ai/kokoro/american-english", { input: { text, voice: "af_heart" } })
LLM:             fal.run("fal-ai/any-llm", { input: { model: "google/gemini-2.5-flash", prompt } })

Примечания

• URL результатов временные (~1 час) — скачивай сразу если нужно сохранить
• seed фиксирует результат для воспроизводимости
• fal.storage.upload() — для загрузки локальных файлов перед передачей в модели
• Старый пакет @fal-ai/serverless-client deprecated → используй @fal-ai/client
• Цены приблизительные — актуальные на fal.ai/pricing