fal Storage API

openapi: 3.2.0
info:
  title: fal Storage API
  description: 'REST endpoints for uploading binary input assets (images, audio, control maps, reference frames) to fal''s CDN so they can be passed by URL when invoking model APIs. Clients first call `/storage/upload/initiate` to obtain a short-lived signed upload URL, then PUT the bytes to the returned URL. Assets are served from `https://v3.fal.media`.

    '
  version: v1
  contact:
    name: fal Support
    url: https://fal.ai/support
  license:
    name: fal Terms of Service
    url: https://fal.ai/legal/terms-of-service
servers:
- url: https://rest.alpha.fal.ai
  description: fal REST control-plane
security:
- FalKeyAuth: []
tags:
- name: Storage
  description: Upload binary assets to the fal CDN.
paths:
  /storage/upload/initiate:
    post:
      summary: Initiate Asset Upload
      description: 'Request a short-lived signed URL to which the client should PUT the file bytes. Returns both the upload URL and the public CDN URL that should be passed to model APIs once the upload completes.

        '
      operationId: initiateUpload
      tags:
      - Storage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateUploadRequest'
            examples:
              PngImage:
                $ref: '#/components/examples/PngImageRequest'
      responses:
        '200':
          description: Signed upload URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateUploadResponse'
              examples:
                Issued:
                  $ref: '#/components/examples/IssuedExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        detail:
          oneOf:
          - type: string
          - type: array
            items:
              type: object
    InitiateUploadRequest:
      type: object
      required:
      - content_type
      - file_name
      properties:
        content_type:
          type: string
          description: MIME type of the asset (e.g. `image/png`, `audio/wav`, `video/mp4`).
        file_name:
          type: string
          description: Original file name. Used to derive the CDN object name.
    InitiateUploadResponse:
      type: object
      required:
      - upload_url
      - file_url
      properties:
        upload_url:
          type: string
          format: uri
          description: Short-lived signed URL. PUT the file bytes here.
        file_url:
          type: string
          format: uri
          description: Public CDN URL to pass to model APIs (e.g. as `image_url`).
  examples:
    IssuedExample:
      summary: Signed upload issued
      value:
        upload_url: https://v3-uploads.fal.media/files/abc/upload?signature=…
        file_url: https://v3.fal.media/files/abc/reference.png
    PngImageRequest:
      summary: PNG image upload
      value:
        content_type: image/png
        file_name: reference.png
  responses:
    ValidationError:
      description: Invalid `content_type` or `file_name`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    FalKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Pass the fal API key as `Authorization: Key $FAL_KEY`.'