> ## Documentation Index
> Fetch the complete documentation index at: https://fal.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload asset

> Upload asset for the authenticated user's fal Assets library.



## OpenAPI

````yaml /api-reference/platform-apis/openapi/v1.json post /assets/uploads
openapi: 3.1.0
info:
  title: Platform APIs
  version: v1
  description: fal REST API for programmatic access to platform resources.
servers:
  - url: https://api.fal.ai/v1
    description: Production server
security: []
paths:
  /assets/uploads:
    post:
      tags:
        - Assets
      summary: Upload asset
      description: Upload asset for the authenticated user's fal Assets library.
      operationId: uploadAsset
      parameters:
        - schema:
            type: string
            description: Optional idempotency key for safe request retries
            example: 550e8400-e29b-41d4-a716-446655440000
          required: false
          description: Optional idempotency key for safe request retries
          name: Idempotency-Key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: fal-hosted media URL to ingest into the asset library
                type:
                  type: string
                  enum:
                    - image
                    - video
                    - audio
                    - 3d
                  description: Media type for the uploaded asset
                prompt:
                  type:
                    - string
                    - 'null'
                  minLength: 1
                  maxLength: 2000
                  description: >-
                    Optional caller-provided caption or description to index
                    with the uploaded asset
                collection_id:
                  type:
                    - string
                    - 'null'
                  description: Optional manual collection ID to add the uploaded asset to
                favorite:
                  type: boolean
                  default: false
                  description: Whether to favorite the uploaded asset immediately
                tag_ids:
                  type: array
                  items:
                    type: string
                  default: []
                  description: Tag IDs to assign to the uploaded asset
              required:
                - url
                - type
            example:
              url: >-
                https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png
              type: image
              prompt: Cinematic portrait of a character
              collection_id: d8b6elcregj72v34jr8g
              favorite: true
              tag_ids:
                - 43ce3411-1a25-4d14-875e-3562d341b090
      responses:
        '201':
          description: Upload ingested
          content:
            application/json:
              schema:
                type: object
                properties:
                  asset:
                    type: object
                    properties:
                      vector_id:
                        type: string
                        description: Vector ID
                        example: b1a2b4a5-cb89-51dc-a108-6dbfd8e742fc
                      request_id:
                        type:
                          - string
                          - 'null'
                        description: Request ID
                        example: 019e6d0a-e5be-7b82-b329-35ae64296902
                      url:
                        type:
                          - string
                          - 'null'
                        description: Media URL
                        example: >-
                          https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png
                      type:
                        type: string
                        enum:
                          - image
                          - video
                          - audio
                          - 3d
                        description: Asset media type
                      title:
                        type: string
                        description: Display title
                        example: Portrait
                      endpoint:
                        type:
                          - string
                          - 'null'
                        description: Model endpoint that produced the asset
                        example: fal-ai/flux/dev
                      created_at:
                        type:
                          - string
                          - 'null'
                        description: Asset creation time
                        example: '2026-05-23T20:00:00.000Z'
                      source:
                        type:
                          - string
                          - 'null'
                        description: Asset source
                        example: upload
                      prompt:
                        type:
                          - string
                          - 'null'
                        description: Saved prompt or description
                        example: cinematic portrait
                      width:
                        type:
                          - number
                          - 'null'
                        description: Width in pixels
                        example: 1024
                      height:
                        type:
                          - number
                          - 'null'
                        description: Height in pixels
                        example: 1024
                      content_type:
                        type:
                          - string
                          - 'null'
                        description: Media content type
                        example: image/png
                      is_favorited:
                        type: boolean
                        description: Whether the asset is favorited
                        example: false
                      collection_ids:
                        type: array
                        items:
                          type: string
                        description: Collections containing this asset
                        example:
                          - d8b6elcregj72v34jr8g
                      tags:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Tag ID
                              example: 43ce3411-1a25-4d14-875e-3562d341b090
                            name:
                              type: string
                              description: Tag name
                              example: moodboard
                            created_at:
                              type:
                                - string
                                - 'null'
                              description: Tag creation time
                              example: '2026-05-23T20:00:00.000Z'
                          required:
                            - id
                            - name
                            - created_at
                          description: Asset tag
                        description: Assigned tags
                      similarity:
                        type:
                          - number
                          - 'null'
                        description: Semantic similarity score when applicable
                        example: 0.92
                    required:
                      - vector_id
                      - request_id
                      - url
                      - type
                      - title
                      - endpoint
                      - created_at
                      - source
                      - prompt
                      - width
                      - height
                      - content_type
                      - is_favorited
                      - collection_ids
                      - tags
                      - similarity
                    description: Asset details
                required:
                  - asset
              example:
                asset:
                  vector_id: b1a2b4a5-cb89-51dc-a108-6dbfd8e742fc
                  request_id: 019e6d0a-e5be-7b82-b329-35ae64296902
                  url: >-
                    https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png
                  type: image
                  title: Cinematic portrait
                  endpoint: fal-ai/flux/dev
                  created_at: '2026-05-23T20:00:00.000Z'
                  source: upload
                  prompt: cinematic portrait of a character
                  width: 1024
                  height: 1024
                  content_type: image/png
                  is_favorited: false
                  collection_ids:
                    - d8b6elcregj72v34jr8g
                  tags:
                    - id: 43ce3411-1a25-4d14-875e-3562d341b090
                      name: moodboard
                      created_at: '2026-05-23T20:00:00.000Z'
                  similarity: 0.92
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: validation_error
                  message: Invalid request parameters
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: authorization_error
                  message: Authentication required
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: authorization_error
                  message: Access denied
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: not_found
                  message: Resource not found
        '409':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: validation_error
                  message: Invalid request parameters
        '422':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: validation_error
                  message: Invalid request parameters
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: rate_limited
                  message: Rate limit exceeded
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: server_error
                  message: An unexpected error occurred
        '502':
          description: Upstream asset service error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: server_error
                  message: Upstream asset service failed
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key must be prefixed with "Key ", e.g. Authorization: Key
        YOUR_API_KEY

````