Inputs and Outputs

In order for your inputs and outputs to be nicely rendered in the playground, you need to use certain conventions that tell our frontend how to interpret the data.

Files

File Input

Name your field with a file_url suffix and it will be rendered as a file in the playground, allowing users to upload or download the file.

from pydantic import BaseModel

class MyInput(BaseModel):
    file_url: str

class MyOutput(BaseModel):
    ...

class MyApp(fal.App):
    @fal.endpoint("/")
    def predict(self, input: MyInput) -> MyOutput:
        input_path = download_file(input.file_url)
        ...
        return MyOutput(...)

Alternatively if that naming convention is not suitable, you can also explicitly tell our frontend to treat it as a file:

from pydantic import BaseModel, Field

class MyInput(BaseModel):
    foo: str = Field(..., ui={"field": "file"})

File Output

from fal.toolkit import File, download_file
from pydantic import BaseModel

class MyInput(BaseModel):
    ...

class MyOutput(BaseModel):
    file: File


class MyApp(fal.App):
    @fal.endpoint("/")
    def predict(self, input: MyInput) -> MyOutput:
        ...
        return MyOutput(file=File.from_path(output_path))

Using File class for your output will include additional metadata about the file:

{
  "file": {
    "url": "https://example.com/file.bin",
    "content_type": "application/octet-stream",
    "file_name": "file.bin",
    "file_size": 1024,
  }
}

Images

Image Input

Name your field with a image_url suffix and it will be rendered as an image in the playground, allowing users to upload or download the image.

from pydantic import BaseModel
from fal.toolkit import download_file

class MyInput(BaseModel):
    image_url: str

class MyOutput(BaseModel):
    ...

class MyApp(fal.App):
    @fal.endpoint("/")
    def predict(self, input: MyInput) -> MyOutput:
        input_path = download_file(input.image_url)
        ...
        return MyOutput(...)

Alternatively if that naming convention is not suitable, you can also explicitly tell our frontend to treat it as an image:

from pydantic import BaseModel, Field

class MyInput(BaseModel):
    foo: str = Field(..., ui={"field": "image"})

Image Output

from fal.toolkit import Image
from pydantic import BaseModel

class MyInput(BaseModel):
    ...

class MyOutput(BaseModel):
    image: Image


class MyApp(fal.App):
    @fal.endpoint("/")
    def predict(self, input: MyInput) -> MyOutput:
        ...
        return MyOutput(image=Image.from_path(output_path))

Using Image class for your output will include additional metadata about the image:

{
  "image": {
    "url": "https://example.com/image.png",
    "content_type": "image/png",
    "file_name": "image.png",
    "file_size": 1024,
    "width": 1024,
    "height": 1024,
  }
}

Image Dataset Input

Use image_urls suffix to render a dataset of images in the playground.

from typing import List
from pydantic import BaseModel

class MyInput(BaseModel):
    image_urls: List[str]

Audio

Audio Input

Name your field with a audio_url suffix and it will be rendered as an audio in the playground, allowing users to upload or download the audio.

from typing import List
from pydantic import BaseModel

class MyInput(BaseModel):
    audio_url: str

class MyOutput(BaseModel):
    ...

class MyApp(fal.App):
    @fal.endpoint("/")
    def predict(self, input: MyInput) -> MyOutput:
        input_path = download_file(input.audio_url)
        ...
        return MyOutput(...)

Alternatively if that naming convention is not suitable, you can also explicitly tell our frontend to treat it as an audio:

from pydantic import BaseModel, Field

class MyInput(BaseModel):
    foo: str = Field(..., ui={"field": "audio"})

Audio Output

from fal.toolkit import Audio
from pydantic import BaseModel

class MyInput(BaseModel):
    ...

class MyOutput(BaseModel):
    audio: Audio


class MyApp(fal.App):
    @fal.endpoint("/")
    def predict(self, input: MyInput) -> MyOutput:
        ...
        return MyOutput(audio=Audio.from_path(output_path))

Using Audio class for your output will include additional metadata about the audio:

{
  "audio": {
    "url": "https://example.com/audio.mp3",
    "content_type": "audio/mpeg",
    "file_name": "audio.mp3",
    "file_size": 1024,
  }
}

Audio Dataset Input

Use audio_urls suffix to render a dataset of audios in the playground.

from typing import List
from pydantic import BaseModel

class MyInput(BaseModel):
    audio_urls: List[str]

Video

Video Input

Name your field with a video_url suffix and it will be rendered as a video in the playground, allowing users to upload or download the video.

from typing import List
from pydantic import BaseModel

class MyInput(BaseModel):
    video_url: str

class MyOutput(BaseModel):
    ...

class MyApp(fal.App):
    @fal.endpoint("/")
    def predict(self, input: MyInput) -> MyOutput:
        input_path = download_file(input.video_url)
        ...
        return MyOutput(...)

Alternatively if that naming convention is not suitable, you can also explicitly tell our frontend to treat it as a video:

from typing import List
from pydantic import BaseModel, Field

class MyInput(BaseModel):
    foo: str = Field(..., ui={"field": "video"})

Video Output

from fal.toolkit import Video
from pydantic import BaseModel

class MyInput(BaseModel):
    ...

class MyOutput(BaseModel):
    video: Video


class MyApp(fal.App):
    @fal.endpoint("/")
    def predict(self, input: MyInput) -> MyOutput:
        ...
        return MyOutput(video=Video.from_path(output_path))

Using Video class for your output will include additional metadata about the video:

{
  "video": {
    "url": "https://example.com/video.mp4",
    "content_type": "video/mp4",
    "file_name": "video.mp4",
    "file_size": 1024,
  }
}

Video Dataset Input

Use video_urls suffix to render a dataset of videos in the playground.

from typing import List
from pydantic import BaseModel

class MyInput(BaseModel):
    video_urls: List[str]