# Flux API via FAL.ai Implementation Guideline ## Introduction This is a guideline for implementing the Flux API via FAL.ai using their official client library (@fal-ai/client). ## Proxy Endpoint Guidelines - **Proxy Endpoint**: - All external api requests on client-side code must go through the proxy endpoint which is already available in `./src/app/api/proxy/route.ts`. - The endpoint supports only two content types: - application/json: set "Content-Type: application/json" and JSON-stringify the body. - multipart/form-data: build the payload with FormData and allow the browser to set Content-Type automatically (including boundary). - **CRITICAL**: Do NOT make calls from other endpoints directly to the proxy endpoint. To call the proxy endpoint, you must make the call from the client-side code, such as in a React component or a Next.js page. - All proxy requests must **include the following fields** in the request body: - `protocol` (string) — e.g., 'https' - `origin` (string) — e.g., 'api.example.com' - `path` (string) — e.g., '/data' - `method` (string) — HTTP method: 'POST | GET | PUT | DELETE'. - `headers` (object) — must always be included; use an empty object `{}` if no headers are needed. - `body` (object | string | FormData) — include request payload or no body key if no body is required. (do not pass an empty body key, just omit it if no body is needed). ## Overview FLUX1.1 [pro] ultra is a next-generation text-to-image model with 10x accelerated speeds, capable of delivering up to 2K resolution with improved photo realism. ## Critical Implementation Notes -**CRITICAL**: Always set up authentication before making any API calls -**CRITICAL**: Handle API responses and errors appropriately -**CRITICAL**: Use proper type definitions for request/response handling -**CRITICAL**: Remember that ALL responses are nested under a 'data' property (use response.data.images, NOT response.images) -**CRITICAL**: The response structure follows this pattern: ```typescript { data: { images: Image[]; // other properties... } } ``` ## Variables Please use the following variable(s) to make an API call to the Flux API via FAL.ai: ```plaintext FAL_KEY = secret_cm9157zvu00003b6rg40werxy ``` The api key is required for all api calls to the FAL AI API. ## Type Definitions ### Request Types ```typescript type AspectRatio = "21:9" | "16:9" | "4:3" | "3:2" | "1:1" | "2:3" | "3:4" | "9:16" | "9:21"; type OutputFormat = "jpeg" | "png"; type SafetyTolerance = "1" | "2" | "3" | "4" | "5" | "6"; interface FluxRequestInput { // Required prompt: string; // Optional seed?: number; // For reproducible results sync_mode?: boolean; // Wait for generation before response num_images?: number; // Default: 1 enable_safety_checker?: boolean; // Default: true safety_tolerance?: SafetyTolerance;// Default: "2" output_format?: OutputFormat; // Default: "jpeg" aspect_ratio?: AspectRatio; // Default: "16:9" raw?: boolean; // Less processed images } ``` ### Response Types ```typescript interface Image { url: string; content_type?: string; // e.g., "image/jpeg" width?: number; height?: number; } interface FluxResponse { data: { // Important: Response is nested under 'data' images: Image[]; // The generated image files info timings: Record; // Returns empty object {} seed: number; // Seed of the generated image has_nsfw_concepts: boolean[]; // NSFW detection per image prompt: string; // Original input prompt }; } ``` ### Important Implementation Notes - The FAL.ai API response is always nested under a `data` property - When accessing images, use `response.data.images` not `response.images` - The `timings` field currently returns an empty object (`{}`) - Example usage: ```typescript const handleResponse = (response: FluxResponse) => { // Correct way to access images const images = response.data.images; // Note: timings is currently an empty object console.log(response.data.timings); // {} // Incorrect way // const images = response.images; // This will be undefined! }; ``` ### Example Response ```json { "data": { "images": [ { "url": "https://storage.url/image.jpg", "content_type": "image/jpeg", "width": 1024, "height": 1024 } ], "timings": { "total": 2.5 }, "seed": 12345, "has_nsfw_concepts": [false], "prompt": "your prompt here" } } ``` ## API Documentation ### Basic Usage The simplest way to generate images using the Flux API: ```typescript import { fal } from "@fal-ai/client"; const generateImage = async (prompt: string): Promise => { return await fal.subscribe("fal-ai/flux-pro/v1.1-ultra", { input: { prompt, }, }); }; ``` ### Advanced Usage Using all available options: ```typescript import { fal } from "@fal-ai/client"; const generateImageAdvanced = async (input: FluxRequestInput): Promise => { return await fal.subscribe("fal-ai/flux-pro/v1.1-ultra", { input, logs: true, onQueueUpdate: (update) => { if (update.status === "IN_PROGRESS") { update.logs.map((log) => log.message).forEach(console.log); } }, }); }; ``` ### Request Parameters 1. **Required Parameters** - `prompt` (string): The text prompt for image generation 2. **Optional Parameters** - `seed` (integer): Seed for reproducible results. Same seed and prompt will generate identical images - `sync_mode` (boolean): When true, waits for image generation before responding - `num_images` (integer): Number of images to generate (default: 1) - `enable_safety_checker` (boolean): Enable content safety checking (default: true) - `safety_tolerance` (string): Safety level from 1-6, where: - "1": Most strict - "6": Most permissive - Default: "2" - `output_format` (string): Image format (default: "jpeg") - Options: "jpeg", "png" - `aspect_ratio` (string): Image aspect ratio (default: "16:9") - Options: "21:9", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16", "9:21" - `raw` (boolean): Generate less processed, more natural-looking images ### Response Format ```typescript { "data": { "images": [ { "url": "https://storage.url/image.jpg", "content_type": "image/jpeg", "width": 1024, "height": 1024 } ], "timings": { "total": 2.5 }, "seed": 12345, "has_nsfw_concepts": [false], "prompt": "your prompt here" }, "requestId": "request-id-here" } ``` ### Error Handling ```typescript try { const result = await generateImage("prompt"); } catch (error) { if (error.response) { // API error response console.error('API Error:', error.response.data); } else if (error.request) { // No response received console.error('Network Error:', error.request); } else { // Other errors console.error('Error:', error.message); } } ``` ## Example Usage (Just an example app made with Flux and Next.js, you can use it as a reference/template) src/types/flux.ts [this comes precommitted in the project template just use it right away as it is the src/types/flux.ts file] ```typescript // Type definitions for FLUX API integration export type AspectRatio = "21:9" | "16:9" | "4:3" | "3:2" | "1:1" | "2:3" | "3:4" | "9:16" | "9:21"; export type OutputFormat = "jpeg" | "png"; export type SafetyTolerance = "1" | "2" | "3" | "4" | "5" | "6"; export interface FluxRequestInput { // Required prompt: string; // Optional seed?: number; sync_mode?: boolean; num_images?: number; enable_safety_checker?: boolean; safety_tolerance?: SafetyTolerance; output_format?: OutputFormat; aspect_ratio?: AspectRatio; raw?: boolean; } export interface GeneratedImage { url: string; content_type?: string; width?: number; height?: number; } export interface FluxResponse { data: { images: GeneratedImage[]; timings: Record; seed: number; has_nsfw_concepts: boolean[]; prompt: string; }; } export interface GenerationState { isLoading: boolean; error: string | null; images: GeneratedImage[]; lastPrompt: string | null; } ``` src/components/ImageGenerator.tsx ```typescript 'use client' import { useState } from 'react' import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card' import { Button } from '@/components/ui/button' import { Input } from '@/components/ui/input' import { Label } from '@/components/ui/label' import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select' import { Badge } from '@/components/ui/badge' import { Loader2, Wand2, Download, Copy, Check } from 'lucide-react' import { toast } from 'sonner' import type { GenerationState, FluxRequestInput, AspectRatio, OutputFormat } from '@/types/flux' export function ImageGenerator(): JSX.Element { const [prompt, setPrompt] = useState('') const [aspectRatio, setAspectRatio] = useState('16:9') const [outputFormat, setOutputFormat] = useState('jpeg') const [numImages, setNumImages] = useState(1) const [state, setState] = useState({ isLoading: false, error: null, images: [], lastPrompt: null, }) const [copiedIndex, setCopiedIndex] = useState(null) const aspectRatioOptions: { value: AspectRatio; label: string }[] = [ { value: '1:1', label: 'Square (1:1)' }, { value: '16:9', label: 'Landscape (16:9)' }, { value: '9:16', label: 'Portrait (9:16)' }, { value: '4:3', label: 'Classic (4:3)' }, { value: '3:2', label: 'Photo (3:2)' }, { value: '21:9', label: 'Ultrawide (21:9)' }, ] const generateImage = async (): Promise => { if (!prompt.trim()) { toast.error('Please enter a description for your image') return } setState(prev => ({ ...prev, isLoading: true, error: null })) try { const requestPayload = { prompt: prompt.trim(), aspect_ratio: aspectRatio, output_format: outputFormat, num_images: numImages, sync_mode: true, enable_safety_checker: true, safety_tolerance: '2', } const response = await fetch('/api/proxy', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ protocol: 'https', origin: 'fal.run', path: '/fal-ai/flux-pro/v1.1-ultra', method: 'POST', headers: { 'Authorization': 'Key secret_cmb8d5s6m0000356ocsvkxapd', 'Content-Type': 'application/json', }, body: JSON.stringify(requestPayload), }), }) if (!response.ok) { const errorText = await response.text() console.error('API Error Response:', errorText) throw new Error(`API request failed: ${response.status} ${response.statusText}`) } const result = await response.json() console.log('API Response:', result) // Handle different possible response formats let images: Array<{ url: string; width?: number; height?: number }> = [] if (result.images && Array.isArray(result.images)) { // Direct images array images = result.images } else if (result.data && result.data.images && Array.isArray(result.data.images)) { // Nested in data object images = result.data.images } else if (result.output && Array.isArray(result.output)) { // Output array format images = result.output.map((item: any) => ({ url: typeof item === 'string' ? item : item.url || item.image_url, width: item.width, height: item.height, })) } else if (typeof result === 'string') { // Single URL string images = [{ url: result }] } else { console.error('Unexpected response format:', result) throw new Error('Unexpected response format from API') } if (images.length === 0) { throw new Error('No images received from API') } setState(prev => ({ ...prev, isLoading: false, images: images, lastPrompt: prompt.trim(), })) toast.success(`Successfully generated ${images.length} image(s)!`) } catch (error) { console.error('Image generation error:', error) const errorMessage = error instanceof Error ? error.message : 'Failed to generate image' setState(prev => ({ ...prev, isLoading: false, error: errorMessage, })) toast.error(`Generation failed: ${errorMessage}`) } } const downloadImage = async (imageUrl: string, index: number): Promise => { try { const response = await fetch(imageUrl) const blob = await response.blob() const url = window.URL.createObjectURL(blob) const a = document.createElement('a') a.href = url a.download = `generated-image-${index + 1}.${outputFormat}` document.body.appendChild(a) a.click() window.URL.revokeObjectURL(url) document.body.removeChild(a) toast.success('Image downloaded!') } catch (error) { toast.error('Failed to download image') } } const copyImageUrl = async (imageUrl: string, index: number): Promise => { try { await navigator.clipboard.writeText(imageUrl) setCopiedIndex(index) setTimeout(() => setCopiedIndex(null), 2000) toast.success('Image URL copied to clipboard!') } catch (error) { toast.error('Failed to copy URL') } } return (

{/* Header */}

FLUX Image Generator

Create amazing images from text using AI

{/* Generation Form */} Generate Your Image Describe the image you want to create in detail

Image Description setPrompt(e.target.value)} className="text-black" disabled={state.isLoading} />

Size

Format

Number of Images

{/* Error Display */} {state.error && (

Error: {state.error}

Please check your internet connection and try again. If the problem persists, the API might be temporarily unavailable.

)} {/* Generated Images */} {state.images.length > 0 && ( Generated Images {state.lastPrompt && ( From prompt: "{state.lastPrompt}" )}

{state.images.map((image, index) => (

Image {index + 1} {image.width && image.height && ( {image.width} × {image.height} )} {outputFormat.toUpperCase()}

))}

)}

) } ``` src/app/page.tsx ```typescript 'use client' import { ImageGenerator } from '@/components/ImageGenerator' import { Toaster } from '@/components/ui/sonner' export default function HomePage(): JSX.Element { return (

) } ```

Noxx ROI Calculator