--- name: fal-image-gen description: "Call fal.ai model APIs for image generation (text-to-image and image-to-image). Use when a user asks to integrate fal, construct requests, run jobs, handle auth, or return image URLs from fal model APIs." ---

Fal Image Gen

Overview

Use this skill to implement text-to-image or image-to-image calls against fal model APIs. Prioritize correctness by checking the current docs for the selected model’s required inputs/outputs and authentication requirements.

Quick Start

1. Identify the target model ID from the fal model API docs.
2. Collect inputs from the user.

• Text-to-image: prompt, optional negative_prompt, size/aspect, steps, seed, safety options.
• Image-to-image: source image URL, strength/denoise, plus prompt/options above.

1. Pick the calling method.

• If the user prefers SDKs: provide Python and/or JavaScript examples.
• If the user prefers REST: provide a curl/HTTP example.

1. Execute the request and return image URL(s) from the response.

Workflow: Text-to-Image

1. Resolve the model ID and schema.

• Open the fal model API docs and confirm the exact input fields and output format.

1. Validate inputs.

• Ensure prompt is non-empty and size/aspect settings are supported by the model.

1. Build the request.

• SDK: call the SDK’s run/submit method with an input object.
• REST: call the model endpoint with a JSON body that matches the schema.

1. Execute and parse output.

• Extract image URL(s) from the response fields defined by the model.

1. Return URLs.

• Provide a clean list of URLs and note any metadata the user asked for (seed, size, etc.).

Workflow: Image-to-Image

1. Resolve the model ID and schema.
2. Validate inputs.

• Ensure the source image is reachable by URL (or converted to the required format).
• Confirm any strength/denoise range constraints from docs.

1. Build the request.

• Include source image + prompt + other options as required by the model.

1. Execute and parse output.

• Extract image URL(s) from the response fields defined by the model.

1. Return URLs.

SDK vs REST Guidance

• Prefer SDKs for simpler auth and retries.
• Prefer REST when the user needs raw HTTP examples, or when running in environments without SDK support.
• Never hardcode API keys. Follow the docs for the required environment variable or header name.

Minimal Examples (Fill From Docs)

Use these as templates only. Replace placeholders after checking the docs.

Python (SDK)

# Pseudocode: replace with the exact fal SDK import + call pattern from docs
import os
# from fal import client  # or the current SDK import

MODEL_ID = "<model-id-from-docs>"
input_data = {
    "prompt": "a cinematic photo of a red fox",
    # "image_url": "https://..."  # for image-to-image
    # "negative_prompt": "...",
    # "width": 1024,
    # "height": 1024,
}

# result = client.run(MODEL_ID, input=input_data)
# urls = extract_urls(result)

JavaScript (SDK)

// Pseudocode: replace with the exact fal SDK import + call pattern from docs
// import { client } from "@fal-ai/client";

const MODEL_ID = "<model-id-from-docs>";
const input = {
  prompt: "a cinematic photo of a red fox",
  // image_url: "https://..." // for image-to-image
};

// const result = await client.run(MODEL_ID, { input });
// const urls = extractUrls(result);

REST (curl)

# Pseudocode: replace endpoint, headers, and payload schema from docs
curl -X POST "https://<fal-api-base>/<model-endpoint>" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cinematic photo of a red fox"
  }'

Resources

• references/fal-model-api-checklist.md: Checklist for gathering inputs and validating responses.
• references/fal-model-examples.md: Example templates for text-to-image, image-to-image, and REST usage.