---
title: "Upload or fetch an asset"
method: POST
path: "/v1/assets/"
tags: ["Assets"]
---

# Upload or fetch an asset

`POST /v1/assets/`

## Request

- Base URL: `https://api.picsha.ai`
- URL: `https://api.picsha.ai/v1/assets/`
- Auth: HTTP bearer

## Query parameters

- `ephemeral` string
- `expires_at` string, date-time

## Headers

- `x-org-id` string
- `x-external-user-id` string

## Request body

- object, nullable
  - `url` string, uri: Direct URL of the external asset to fetch, store, and process.
  - `s3Key` string: S3 Key of a file already uploaded directly via presigned URL or resumable TUS.
  - `originalName` string: Original filename for S3 pre-uploaded assets.
  - `tags` string[]: Initial tags to attach to the asset.
  - `metadata` object: Initial metadata dictionary to attach to the asset.
  - `config` object: Ingestion pipeline options to customize processing.
    - `auto_tag` boolean: Whether to run AWS Rekognition Vision AI for face and object detection. Defaults to true.
    - `auto_summarize` boolean: Whether to run AI summaries (Claude 3 Haiku for images, Titan/Claude for documents, Amazon Transcribe for audio/video). Defaults to true.
    - `vectorize` boolean: Whether to generate a Titan multimodal embedding vector for similarity search. Defaults to true.
    - `location_lookup` boolean: Whether to reverse-geocode EXIF GPS coordinates via Google Maps API. Defaults to true.
    - `adaptive_stream` boolean: Whether to transcode video to adaptive HLS stream using AWS MediaConvert. Defaults to false.
    - `content_moderation` boolean: Whether to run AWS Rekognition Content Moderation. Defaults to false (the worker runs it only when explicitly true).
    - `antivirus_scan` boolean: Whether to run the ClamAV malware scan at ingest. Defaults to true; set false to opt out.
    - `quality_metrics` boolean: Whether to compute deterministic image quality metrics (sharpness, brightness, contrast, clipping) and face attributes. Defaults to true; set false to opt out.
    - `remove_background` boolean: Whether to generate a background-removed alpha cutout at ingest for instant background compositing at render time. Defaults to false.
    - `render_on_upload` string: Semicolon-separated delivery parameters to pre-warm the CDN cache (e.g. "w=300&q=80; w=800").
    - `expires_at` string, date-time: ISO-8601 timestamp for automatic asset deletion.

## Response `200`

Default Response

- object
  - `id` string, required
  - `url` string, nullable
  - `message` string, required

## Other responses

- `201`: Default Response
- `400`: Default Response
- `403`: Default Response
- `500`: Default Response

---

[API](https://skmtc.dev/picsha/apis/picsha-ai-api.md) · [All operations](https://skmtc.dev/picsha/apis/picsha-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/picsha/apis/picsha-ai-api/revisions/f77c6ac40e70?raw)