openapi: 3.1.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:
  securitySchemes:
    FalKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Pass the fal API key as `Authorization: Key $FAL_KEY`.'

  schemas:
    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`).

    ErrorResponse:
      type: object
      properties:
        detail:
          oneOf:
            - type: string
            - type: array
              items:
                type: object

  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Invalid `content_type` or `file_name`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  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