---
title: "Upload asset"
method: POST
path: "/assets/uploads"
tags: ["Assets"]
---

# Upload asset

`POST /assets/uploads`

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

## Headers

- `Idempotency-Key` string — Optional idempotency key for safe request retries

## Request body

- object
  - `url` string, uri, required — fal-hosted media URL to ingest into the asset library
  - `type` 'image' | 'video' | 'audio' | '3d', required — Media type for the uploaded asset
  - `prompt` string, nullable — Optional caller-provided caption or description to index with the uploaded asset
  - `collection_id` string, nullable — Optional manual collection ID to add the uploaded asset to
  - `favorite` boolean — Whether to favorite the uploaded asset immediately
  - `tag_ids` string[] — Tag IDs to assign to the uploaded asset

## Response `201`

Upload ingested

- object
  - `asset` object, required — Asset details
    - `asset_id` string, nullable, required — Asset ID (canonical catalog identity)
    - `vector_id` string, required — Vector ID. Prefer asset_id for addressing
    - `request_id` string, nullable, required — Request ID
    - `url` string, nullable, required — Media URL
    - `type` 'image' | 'video' | 'audio' | '3d', required — Asset media type
    - `title` string, required — Display title
    - `endpoint` string, nullable, required — Model endpoint that produced the asset
    - `created_at` string, nullable, required — Asset creation time
    - `source` string, nullable, required — Asset source
    - `prompt` string, nullable, required — Saved prompt or description
    - `width` number, nullable, required — Width in pixels
    - `height` number, nullable, required — Height in pixels
    - `content_type` string, nullable, required — Media content type
    - `is_favorited` boolean, required — Whether the asset is favorited
    - `collection_ids` string[], required — Collections containing this asset
    - `tags` object[], required — Assigned tags
      - `id` string, required — Tag ID
      - `name` string, required — Tag name
      - `created_at` string, nullable, required — Tag creation time
    - `similarity` number, nullable, required — Semantic similarity score when applicable

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication required
- `403` — Access denied
- `404` — Resource not found
- `409` — Invalid request parameters
- `422` — Invalid request parameters
- `429` — Rate limit exceeded
- `500` — Internal server error
- `502` — Upstream asset service error

---

[API](https://skmtc.dev/fal/apis/platform-apis.md) · [All operations](https://skmtc.dev/fal/apis/platform-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fal/platform-apis/revisions/0c7dabf80b00/schema)