> 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/recipes/upload-an-asset.md).

# Upload an asset

Upload a local or hosted image to FLORA with the TypeScript SDK or curl and use the resulting asset URL as a Technique or generation input.

To run a Technique or generation on your own image or video, get the file into FLORA first and pass the asset's URL as the input. This recipe covers doing that from your own code with the TypeScript SDK or curl.

Working from an AI client such as Claude, ChatGPT or a coding agent? FLORA MCP has its own upload flow, including a browser upload link for chat clients. See [Upload your own images, video and files](https://docs.flora.ai/mcp/recipes/upload-files.md).

**What you'll build:** a flow that takes a local file path or a hosted URL, uploads it, and returns a ready FLORA URL to use as an input.

## Choose a path

| You have                                       | Do this                                            |
| ---------------------------------------------- | -------------------------------------------------- |
| A local file, and you use TypeScript           | `client.assets.upload()`: one call, any size       |
| A file at a public `https://` URL              | Pass the URL; FLORA fetches it (up to 50 MB)       |
| A local file of 4 MB or less, and you use curl | Send the bytes directly as `multipart/form-data`   |
| A larger local file, and you use curl          | Signed upload: reserve, `POST` the bytes, complete |
| Many files                                     | Reserve and complete up to 25 per request          |

Allowed types are images (JPEG, PNG, WebP, GIF, AVIF, HEIC, HEIF), video (MP4, WebM, QuickTime), audio (MP3, WAV, OGG, M4A) and PDF. Never base64-encode a file into a JSON body.

## TypeScript: one call

`client.assets.upload()` takes a file path, a public URL, a `File` or `Blob`, or raw bytes. It sends small files directly, uses a signed upload for large ones, lets FLORA fetch URLs itself, then waits until the asset is ready:

```ts
import { FloraClient } from "@flora-ai/flora"

const client = new FloraClient()

const asset = await client.assets.upload("./photo.png", {
  workspace_id: "ws_abc123",
  project_id: "prj_abc123", // optional: also puts the asset on this project's canvas
})

console.log(asset.asset_id, asset.status, asset.url)
```

A hosted file works the same way, without downloading it first:

```ts
const asset = await client.assets.upload("https://example.com/photo.png", { workspace_id: "ws_abc123" })
```

If the host needs a login or blocks hotlinking, FLORA can't fetch it. Download the file and upload it from disk instead.

## curl: direct bytes (4 MB or smaller)

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

The response is the asset, with its `url`.

## Signed upload with curl

For files over 4 MB, reserve an upload, send the bytes straight to storage, then mark the asset complete. This script needs `jq`:

```bash
FILE=./product.mp4

# 1. Reserve
RESERVATION=$(curl -s -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"}')

ASSET_ID=$(jq -r '.asset_id' <<<"$RESERVATION")
UPLOAD_URL=$(jq -r '.upload.url' <<<"$RESERVATION")
FILE_FIELD=$(jq -r '.upload.file_field' <<<"$RESERVATION")

# 2. Upload: every returned form field exactly as given, then the file last.
#    No FLORA Authorization header: this request goes to storage, not the API.
FORM=()
while IFS= read -r field; do
  FORM+=(--form-string "$field")
done < <(jq -r '.upload.form_fields | to_entries[] | "\(.key)=\(.value)"' <<<"$RESERVATION")

curl -# -X POST "$UPLOAD_URL" "${FORM[@]}" -F "$FILE_FIELD=@$FILE" \
  -w "\nHTTP %{http_code}, uploaded %{size_upload} bytes in %{time_total}s\n"

# 3. Complete
curl -s -X POST "https://app.flora.ai/api/v1/assets/$ASSET_ID/complete" \
  -H "Authorization: Bearer $FLORA_API_KEY" | jq '{asset_id, status, url}'
```

Copy the form fields mechanically; don't edit them or ask anyone for storage credentials. If the reservation expires before you upload, call `POST /assets/{assetId}/retry` for fresh instructions.

## Use it as an input

The ready asset's `url` is a public HTTPS URL, so it works for any `imageUrl` or `videoUrl` Technique input:

```ts
const run = await client.techniques.runs.create({
  techniqueId: "portrait-enhancer",
  inputs: [{ id: "input_image", type: "imageUrl", value: asset.url }],
  mode: "async",
})
```

For a generation, pass it in the model's image parameter (such as `image_url`, listed in `GET /models`). See [Generations](https://docs.flora.ai/api/guides/generations.md#use-your-own-images).

## Attach it to a project

Passing `project_id` at upload puts the asset on that project's canvas. To add an existing asset to a project later:

```ts
await client.projects.assets.attach({ projectId: "prj_abc123", assetId: asset.asset_id })
```

## Upload many files

Every request counts against your workspace's rate limit. For many files, reserve up to 25 signed uploads in one request with `POST /assets/reserve`, upload each file with its own `upload` instructions, then complete them in one request with `POST /assets/complete`. Each counts once, however many files it carries. See [Assets](https://docs.flora.ai/api/guides/assets.md#upload-many-files) for the request and response shapes.

## Tips

* Wait for `status: "ready"` before you pass the URL to a run. `client.assets.upload()` does this for you.
* Upload ahead of time. Don't put an upload in the critical path of an interactive UI without a loading state.
* A `failed` asset has a `failure_message`, often an unsupported type or a file over the size or 150-megapixel limit.

## Related

* [Assets](https://docs.flora.ai/api/guides/assets.md): every asset endpoint.
* [Generate a grid](https://docs.flora.ai/api/recipes/generate-a-grid.md): use the uploaded asset as an input.
* [Iterate on outputs](https://docs.flora.ai/api/recipes/iterate-on-outputs.md): combine uploaded references with generated outputs.


---

# 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/recipes/upload-an-asset.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.
