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

# Upload an asset

`POST /v1/assets`

## Request

- Base URL: `https://nanostudiopro.com/api`
- URL: `https://nanostudiopro.com/api/v1/assets`
- Auth: HTTP bearer

Multipart upload of a single image to your asset library. Use this when you have a reference you'll reuse across multiple generations — for example a recurring model headshot or a brand-approved background. For one-off references, attaching to `POST /v1/generations` directly is fine; that endpoint also saves uploads as assets automatically. Counts against your storage quota.

## Response `200`

The same file (byte for byte) was already uploaded to this account in this category: the existing asset comes back with `duplicate: true`. Nothing is stored, scanned or charged; a `project_id` adds it to that project.

- Asset
  - `id` string
  - `category` 'model' | 'pose' | 'background' | 'shoe' | 'accessory' | 'upload' | 'product'
  - `name` string
  - `file_path` string: Internal storage key (use `url` for fetching).
  - `url` string, uri: Signed URL tied to a ~6-hour signing window. Use this to display or download the asset; re-fetch the resource for a fresh one.
  - `permanent_url` string, uri: A link that never expires: embed it in a page, an email or another product. Append `&size=xs|thumb|preview|large|original` (default original). Anyone holding it can view this one image; deleting the asset revokes it. See `GET /v1/media/{type}/{id}`.
  - `project_id` string, nullable
  - `metadata` object, nullable: The fields you sent as `metadata` on upload, returned unchanged.
  - `width` integer, nullable
  - `height` integer, nullable
  - `size` integer, nullable: File size in bytes.
  - `mime_type` string, nullable
  - `created_at` string, date-time

## Other responses

- `201`: Asset created. When other versions of the same picture are already in your library (a larger original, a smaller export, a re-save), the answer adds `versions`: see `GET /v1/media/{type}/{id}/versions`. Nothing is refused over it.
- `400`: Invalid upload
- `401`: Missing or invalid token
- `402`: Storage quota exceeded
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api.md) · [All operations](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/revisions/7f7d4a72b17c?raw)