FalBaseModel for field ordering and hidden fields, specialized field helpers (ImageField, VideoField, AudioField) for Playground rendering, and toolkit types (Image, Video, Audio, File) for returning media with metadata. For the runtime side of file handling (downloading user inputs and uploading generated outputs to CDN), see Working with Files.
FalBaseModel
For the best experience defining inputs and outputs, useFalBaseModel from the fal SDK. It extends Pydantic’s BaseModel with features specifically designed for fal applications:
- Field ordering - Control the order fields appear in the playground and API schema
- Hidden fields - Mark parameters as API-only, hiding them from the playground and API schema.
Field ordering
Use theFIELD_ORDERS class variable to control the order fields appear in the API schema and playground. Fields listed in FIELD_ORDERS appear first, in the specified order, followed by any remaining fields.
This is particularly useful when you have a base model with common fields that multiple models inherit from. By default, Pydantic places child class fields before parent class fields in the schema. FIELD_ORDERS lets you ensure base model fields (like prompt) appear first for a consistent user experience.
Hidden fields
UseHidden() to wrap any field that should be available via API but hidden from the playground UI. This is useful for:
- Testing parameters you want to expose to select API integrations
- Internal debugging flags
- Advanced options that would clutter the UI
Media field helpers
For better playground rendering, use the specialized field helpers instead of plainField():
| Helper | UI Rendering |
|---|---|
FileField(...) | Generic file upload |
ImageField(...) | Image upload/preview |
AudioField(...) | Audio upload/player |
VideoField(...) | Video upload/player |
Output Format for Playground Rendering
The Playground detects media outputs by checking for objects that have both aurl and content_type field. If you use the toolkit types (Image, Video, Audio, File), these fields are set automatically. But if you are returning raw dicts from a custom Docker container or a fal.function endpoint, you must include both fields for the Playground to render the output as media instead of raw JSON.
| Output field | Renders as |
|---|---|
image or images | Image preview / gallery |
video | Video player |
audio, audio_file, or audio_url | Audio player |
model_glb, model_obj, model_mesh | 3D model viewer |
url and content_type. Without content_type, the Playground falls back to displaying the result as raw JSON. Additional fields like file_name, file_size, width, and height are optional but improve the display.
For streaming endpoints that send results via SSE, the same format applies to each event. Streaming endpoints typically use data: URIs (base64-encoded inline content) instead of CDN URLs, since uploading each intermediate frame to CDN would add latency. The Playground renders data URIs the same way as CDN URLs.
Standard Inputs and Outputs
File Input
Name your field with afile_url suffix and it will be rendered as a file in the playground, allowing users to upload or download the file.
FileField helper:
Manual approach with json_schema_extra
Manual approach with json_schema_extra
For advanced use cases, you can manually specify the
ui metadata. The syntax differs between Pydantic versions:File Output
Use theFile type from fal.toolkit in your output schema. The Playground renders it as a download link.
File objects from local paths or bytes.
Image Input
Name your field with aimage_url suffix and it will be rendered as an image in the playground, allowing users to upload or download the image.
ImageField helper:
Manual approach with json_schema_extra
Manual approach with json_schema_extra
For advanced use cases, you can manually specify the
ui metadata. The syntax differs between Pydantic versions:Image Output
Use theImage type in your output schema. The Playground renders it as an image preview.
Image objects from PIL images, bytes, or local files.
Multiple Image Output
Return a list ofImage objects to output multiple images. The Playground renders them in a gallery grid.
- 1 image: Full width
- 2 images: Side by side (index 0 left, index 1 right)
- 3 images: First image full width on top, then index 1 left and index 2 right below
- 4 images: 2x2 grid (index 0 top-left, index 1 top-right, index 2 bottom-left, index 3 bottom-right)
has_nsfw_concepts array maps by index: has_nsfw_concepts[i] corresponds to images[i].
Image Dataset Input
Useimage_urls suffix to render a dataset of images in the playground.
Audio Input
Name your field with aaudio_url suffix and it will be rendered as an audio in the playground, allowing users to upload or download the audio.
AudioField helper:
Manual approach with json_schema_extra
Manual approach with json_schema_extra
For advanced use cases, you can manually specify the
ui metadata. The syntax differs between Pydantic versions:Audio Output
Use theAudio type in your output schema. The Playground renders it as an audio player with waveform visualization.
Audio objects from local files or bytes.
Multiple Audio Output
Return a list ofAudio objects. The Playground renders each as a stacked waveform player.
audios (array), audio (single or array), or audio_file. Audio outputs are displayed vertically with waveform visualization and playback controls, in array order.
Audio Dataset Input
Useaudio_urls suffix to render a dataset of audios in the playground.
Video Input
Name your field with avideo_url suffix and it will be rendered as a video in the playground, allowing users to upload or download the video.
VideoField helper:
Manual approach with json_schema_extra
Manual approach with json_schema_extra
For advanced use cases, you can manually specify the
ui metadata. The syntax differs between Pydantic versions:Video Output
Use theVideo type in your output schema. The Playground renders it as a video player.
Video objects from local files or bytes.
Multiple Video Output
Return a list ofVideo objects. The Playground renders each video as a stacked player (not a grid).
videos (array of objects with url) or video (single object or array). Videos are displayed vertically, one player per video, in array order.
Video Dataset Input
Usevideo_urls suffix to render a dataset of videos in the playground.
Mask Image Input
Name your field with amask_image_url or mask_url suffix (or prefix) and the Playground renders an image upload with a built-in mask painting tool. Users can upload a mask image directly or click “Create…” to draw a mask over a reference image. The reference image is automatically pulled from an image_url or inpaint_image_url field in the same input schema.
mask_image_url and mask_url prefixes/suffixes are supported (e.g., mask_url_face, custom_mask_image_url).
Color Input
If your input uses a Pydantic model namedRGBColor with r, g, b integer fields, the Playground renders a color picker with a visual swatch and individual R/G/B inputs (0-255). A list of RGBColor values renders a color palette editor where users can add and remove colors.
The Playground detects this by the type name
RGBColor. The model must be named exactly RGBColor for the color picker to render.Image Size Input
UseImageSizeInput from fal.toolkit to render an image size selector with preset buttons (square, landscape, portrait) and custom width/height inputs. This is the same type used by most image generation models on fal.
"square_hd" (1024x1024), "square" (512x512), "portrait_4_3" (768x1024), "portrait_16_9" (576x1024), "landscape_4_3" (1024x768), and "landscape_16_9" (1024x576). Users can also enter custom dimensions directly.
Camera Image Input
Name your field with aface_image_url suffix and the Playground renders a camera capture widget that lets users take a photo with their webcam, in addition to the standard file upload options.
Camera Control Input
Useui.field = "camera_control" or name your field ending with advanced_camera_control to render a visual camera motion selector. Users pick a movement type (roll, pan, tilt, zoom, horizontal, vertical) and a value, which is useful for video generation models that accept camera motion parameters.
3D Model Input
Name your field with amodel_url suffix and the Playground renders a 3D model upload widget.
Archive and Dataset Input
Name your field with adata_url or archive_url suffix to render a dataset upload widget. This is useful for training endpoints or batch processing that accept ZIP archives or collections of files.
Presets Input
Fields ending inmodel_name automatically render as a preset selector. The Playground shows a dropdown populated from the field’s examples metadata, with an option to enter a custom value. This is useful for model selection fields where you want to suggest common options while allowing arbitrary input.
EXR / HDR Output
The Playground can render OpenEXR files with HDR tone mapping. When your endpoint returns a file with a URL ending in.exr, the Playground automatically displays it using a WebGL-based HDR viewer with ACES Filmic tone mapping.
Use File.from_path() to return EXR files — the Image toolkit class does not support EXR format.
EXR rendering in the Playground is output only. Uploading EXR files as input is not currently supported.
3D Model Output
The Playground can render 3D model files with an interactive viewer (orbit controls, lighting, zoom). When your endpoint returns a file with one of the supported extensions, the Playground automatically displays it as a 3D scene. Supported formats:| Format | Extension | Renderer |
|---|---|---|
| glTF Binary | .glb | Google Model Viewer (AR-capable) |
| Wavefront OBJ | .obj | Three.js with orbit controls |
| FBX | .fbx | Three.js with animation support |
| Mesh | .mesh | Google Model Viewer |
File.from_path() to return 3D files with the correct extension:
Playground UI Mapping
Your Pydantic schema controls how the Playground renders each input field. The Playground automatically selects the right widget based on the field’s type, name, and metadata.Widget Reference
| Python Type / Pattern | Playground Widget |
|---|---|
str | Text input |
str named prompt or ending in _prompt | Textarea (3 rows) |
bool | Toggle switch |
int or float with ge and le | Slider + number input |
int ending in seed | Number input + randomize button |
Literal["a", "b", "c"] or Enum | Dropdown select |
List[Literal[...]] or List[Enum] | Checkboxes |
str ending in _image_url or ImageField | Image upload (drag-drop, paste, URL) |
str ending in _face_image_url | Camera capture + image upload |
str ending in _mask_image_url or _mask_url | Image upload + mask painter |
str ending in _video_url or VideoField | Video upload with preview |
str ending in _audio_url or AudioField | Audio upload + microphone recording |
str ending in _file_url or FileField | Generic file upload |
str ending in _model_url | 3D model upload |
str ending in _data_url or _archive_url | Dataset/archive upload |
str ending in model_name with examples | Preset selector + custom input |
List[Image] or ending in _image_urls | Multi-image picker |
RGBColor model (with r, g, b fields) | Color picker |
List[RGBColor] | Color palette editor |
ImageSizeInput (from fal.toolkit) | Image size selector (presets + custom) |
ui.field = "camera_control" | Camera motion selector |
| Nested Pydantic model | Recursive form (indented section) |
List[str] or List[int] | Add/remove input list |
Examples
Slider - anyint or float with both ge (min) and le (max) renders as a slider. Use multiple_of to control the step precision:
Literal types or Python Enum classes render as dropdown selects:
int field with a name ending in seed gets a randomize button:
prompt automatically render as a multi-line textarea. For other fields, use ui.field:
UI Metadata
You can control Playground behavior withjson_schema_extra metadata on any field:
| Property | Effect |
|---|---|
ui.field | Override widget type ("textarea", "image", "video", "audio", "file", "seed", "camera_control", "presets") |
ui.hint | Helper text shown below the field |
ui.frozen | Field is read-only with an “API only” badge |
ui.important | Field appears in the main form section |
Field Grouping
The Playground automatically groups fields into two sections:- Main form: Required fields and fields marked with
ui.important = true - Additional Settings: Optional fields with defaults