> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/api/guides/assets.md).

# Assets

Upload images, video, audio and PDFs to FLORA with the API, by URL, direct bytes or a signed upload, then retrieve, retry and attach them to projects.

Assets are media files stored in FLORA: images, video, audio and PDFs you can pass to Technique and generation inputs or place on a project's canvas. You create one in one of three ways, depending on where the file is:

| The file is                | Use                                                    | Size limit |
| -------------------------- | ------------------------------------------------------ | ---------- |
| At a public `https://` URL | Server-side fetch: `source` is the URL                 | 50 MB      |
| Local, 4 MB or smaller     | Direct bytes: `multipart/form-data` with a `file` part | 4 MB       |
| Local, larger than 4 MB    | Signed upload: reserve, upload the bytes, complete     | See below  |

The TypeScript SDK's `client.assets.upload()` picks the right path for you. See [Upload an asset](https://docs.flora.ai/api/recipes/upload-an-asset.md) for a full walkthrough.

Allowed types: images (`image/jpeg`, `png`, `webp`, `gif`, `avif`, `heic`, `heif`, up to 150 megapixels), video (`video/mp4`, `webm`, `quicktime`), audio (`audio/mpeg`, `wav`, `ogg`, `mp4`), `application/pdf`, and GLB 3D models (`model/gltf-binary`). A GLB needs `project_id`, and a signed GLB upload also needs `size_bytes` set to the exact file size.

## Create from a URL

If the file is already at a public HTTPS URL, pass that URL as `source`. FLORA fetches the bytes itself:

```bash
curl -X POST https://app.flora.ai/api/v1/assets \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://example.com/product.png",
    "workspace_id": "ws_abc123"
  }'
```

FLORA won't fetch `http://` URLs, URLs with credentials, or private and internal addresses. If a host needs a login or blocks hotlinking, download the file and use a signed upload instead.

## Upload bytes directly (4 MB or smaller)

Send the file as `multipart/form-data`. The response is the finished asset:

```bash
curl -X POST https://app.flora.ai/api/v1/assets \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -F "workspace_id=ws_abc123" \
  -F "file=@./product.png"
```

## Signed upload (larger files)

### 1. Reserve

```bash
curl -X POST https://app.flora.ai/api/v1/assets \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "signed-url",
    "workspace_id": "ws_abc123",
    "file_name": "product.mp4",
    "content_type": "video/mp4",
    "folder": "api-uploads"
  }'
```

Response:

```json
{
  "asset_id": "asset_abc123",
  "uploaded_via": "signed_url",
  "url": "https://...",
  "workspace_id": "ws_abc123",
  "visibility": "workspace",
  "status": "pending_upload",
  "upload": {
    "url": "https://storage.googleapis.com/...",
    "method": "POST",
    "content_type": "multipart/form-data",
    "file_field": "file",
    "form_fields": { "key": "...", "policy": "..." }
  },
  "expires_at": "2026-10-11T12:15:00.000Z"
}
```

### 2. Upload the bytes

`POST` a multipart form to `upload.url` with every entry in `upload.form_fields`, exactly as returned, then the file last in the `upload.file_field` part. The upload target isn't the FLORA API, so don't send your `Authorization` header to it. A GLB reservation returns a `PUT` descriptor instead: send the raw file bytes to `upload.url` with `upload.headers`. [Upload an asset](https://docs.flora.ai/api/recipes/upload-an-asset.md#signed-upload-with-curl) has a script that builds the command from the response.

### 3. Complete

```bash
curl -X POST https://app.flora.ai/api/v1/assets/asset_abc123/complete \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

A completed asset has `status: "ready"`, or `failed` with a `failure_message`. Completing the same upload twice is safe and returns the ready asset.

## Upload many files

Every request counts against the workspace's rate limit, so reserve and complete files in batches of up to 25 instead of one request per file. `workspace_id`, `project_id` and `folder` apply to every upload; an upload's own `folder` overrides the shared one.

```bash
curl -X POST https://app.flora.ai/api/v1/assets/reserve \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_abc123",
    "uploads": [
      { "file_name": "front.png", "content_type": "image/png" },
      { "file_name": "back.png", "content_type": "image/png" }
    ]
  }'
```

Each entry in the response's `assets` echoes its `index` and carries either the single reservation's fields with `ok: true`, or `ok: false` with an `error`. A failed entry never stops the rest. A workspace your key can't write, or a `project_id` outside the workspace, fails the whole request. Upload each file with its own `upload` instructions, then complete the batch:

```bash
curl -X POST https://app.flora.ai/api/v1/assets/complete \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "asset_ids": ["asset_abc123", "asset_def456"] }'
```

Each entry reports `status` `ready`, or `failed` with `failure_message`, as a single completion does. An asset that's missing or outside your key's write access reports `ok: false` with `not_found`. Uploads reserved with a `project_id` land on that project's canvas when they complete.

## List assets

```bash
curl "https://app.flora.ai/api/v1/assets?workspace_id=ws_abc123&limit=10" \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

Filter with `project_id` or `query`, and page with `cursor`.

## Retrieve an asset

```bash
curl https://app.flora.ai/api/v1/assets/asset_abc123 \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

## Retry an upload

If a signed upload expired or failed, request fresh upload instructions for the same asset:

```bash
curl -X POST https://app.flora.ai/api/v1/assets/asset_abc123/retry \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

An upload that already completed can't be retried; check it with `GET /assets/{assetId}` first.

## Attach an asset to a project

Pass `project_id` when you create the asset, or attach it later:

```bash
curl -X POST https://app.flora.ai/api/v1/projects/prj_abc123/assets/asset_abc123/attach \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

## Common endpoints

| Method | Path                                            | Description                                                                                                                  |
| ------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| POST   | `/assets`                                       | [Create an asset from a URL or bytes, or reserve a signed upload](https://docs.flora.ai/api/reference/assets/uploadasset.md) |
| POST   | `/assets/{assetId}/complete`                    | [Mark a signed upload complete](https://docs.flora.ai/api/reference/assets/completeassetupload.md)                           |
| POST   | `/assets/reserve`                               | [Reserve up to 25 signed uploads](https://docs.flora.ai/api/reference/assets/reserveassetuploads.md)                         |
| POST   | `/assets/complete`                              | [Complete up to 25 signed uploads](https://docs.flora.ai/api/reference/assets/completeassetuploads.md)                       |
| GET    | `/assets?workspace_id={workspace_id}`           | [List assets](https://docs.flora.ai/api/reference/assets/listassets.md)                                                      |
| GET    | `/assets/{assetId}`                             | [Retrieve an asset](https://docs.flora.ai/api/reference/assets/getasset.md)                                                  |
| POST   | `/assets/{assetId}/retry`                       | [Get new upload instructions](https://docs.flora.ai/api/reference/assets/retryassetupload.md)                                |
| POST   | `/projects/{projectId}/assets/{assetId}/attach` | [Attach an asset to a project](https://docs.flora.ai/api/reference/canvas/attachcanvasasset.md)                              |

Full parameters and responses are in the [FLORA API reference](https://docs.flora.ai/api/reference.md).

## Common validation issues

* `source` is required for JSON requests and must be a string: `"signed-url"` or a public `https://` URL. Objects like `{ "url": "..." }`, local paths, `data:` URLs and placeholders like `"upload"` or `"file"` are rejected.
* `workspace_id` is required and must start with `ws_`.
* `content_type` must be one of the allowed types above.
* If a public URL you expected to work is rejected, tell FLORA with [feedback](https://docs.flora.ai/api/guides/feedback.md) (`kind: "missing_capability"`).

## Notes

* Wait for `status: "ready"` before you use a new asset as an input.
* Keep the asset's `url`; that's what you pass to an `imageUrl` or `videoUrl` input.
* Uploading from an AI client with FLORA MCP works differently; see [Upload your own images, video and files](https://docs.flora.ai/mcp/recipes/upload-files.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/api/guides/assets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
