openapi: 3.1.0
info:
  title: fal Model APIs Apps Storage API
  description: 'The fal Model APIs are a unified queue-based REST surface for invoking 1,000+ production generative image, video, audio, and multimodal models hosted on fal''s GPU inference infrastructure. Clients submit a job to `https://queue.fal.run/{model-owner}/{model-name}`, then either poll for status and result, subscribe via webhook, or stream incremental progress.

    '
  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://queue.fal.run
  description: Production queue endpoint
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:
  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'
  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:
    PngImageRequest:
      summary: PNG image upload
      value:
        content_type: image/png
        file_name: reference.png
    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
  securitySchemes:
    FalKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Pass the fal API key as `Authorization: Key $FAL_KEY`. Keys are issued from the fal dashboard at https://fal.ai/dashboard/keys.

        '