media-gen

Media Generation (Fal.ai) — v3.0

Black Forest Labs FLUX Prompting Guide Reference: The official FLUX prompting guide is at https://docs.bfl.ml/guides/prompting_summary.md All photography terminology below is sourced from BFL's official Prompt Reference (https://docs.bfl.ml/guides/prompting_unified_reference.md)

Key principle from BFL: "Prompt the model as if describing a real photograph: specify lens, lighting, framing, and texture details for maximum realism."

How FLUX reads prompts: Write in prose, not keyword lists — describe scenes like a novelist. Lighting descriptions have the highest single impact on output quality.

---

Setup

# Prerequisites
export FAL_KEY="your-key-here"   # On Windows: setx FAL_KEY "key" (restart terminal)
pip install fal-client

# CRITICAL: fal-client >= 1.0.0 required for CDN upload (image-to-image)
# Old v0.13.1 broke CDN auth. Upgrade: pip install --upgrade fal-client

CRITICAL: FAL_KEY must use shell expansion, not the literal string. Hardcoding the key string (FAL_KEY="07138a1e-...") returns 401 even when the shell-expanded version (FAL_KEY="$FAL_KEY") works. The env var may contain escape characters or may have been rotated since you read it. ✅ FAL_KEY="$FAL_KEY" python scripts/generate.py ... ❌ FAL_KEY="07138a1e-..." python scripts/generate.py ...

(Run in foreground, not background, to avoid env-var drop issues)

Direct Python API (fal_client v1.0.0)

You can bypass generate.py and call FAL directly with synchronous API — useful for quick scripts or when you need precise control over parameters:

import fal_client

# Upload a reference image to FAL CDN (SYNCHRONOUS in v1.0.0, do NOT await)
image_url = fal_client.upload_file('C:/Users/ali/product_primary.png')

# Image-to-image with Nano Banana Pro Edit
result = fal_client.run('fal-ai/nano-banana-pro/edit', arguments={
    'image_urls': [image_url],        # REQUIRED: ARRAY, not a single string
    'prompt': 'Your photography-grade prompt...',
    'strength': 0.85                   # 0.70-0.90 range; higher = more original image preserved
})

# Result shape: {'images': [{'url': '...', ...}], 'description': 'model reasoning'}
output_url = result['images'][0]['url']