---
title: "Import an image into a project timeline"
method: POST
path: "/v1/generations/upload"
tags: ["Generations"]
---

# Import an image into a project timeline

`POST /v1/generations/upload`

## Request

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

Imports a single local image directly into a project's timeline as a generation — **no prompt, no AI, no effect**. The image is stored under your storage prefix and appears in the project's timeline immediately, just like a generated image. Counts against your **storage quota**.

Use this when you want to bring an external photo into a project so it can be used as a source for cutouts, restyles, or other operations that operate on existing generations.

### Request

Multipart only. The `file` and `project_id` fields are required; `name` is optional (auto-derived from the filename if omitted).

### Response

Returns the full generation object (same shape as `GET /v1/generations`) with a signed `image_url`.

## Response `201`

Image imported and available as a generation. 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.

- Generation: A stored generation as returned in list responses.
  - `id` string
  - `project_id` string
  - `name` string, nullable
  - `metadata` object, nullable: The fields you sent as `metadata` when uploading or importing it, returned unchanged.
  - `image_url` string, uri: Signed URL to the generated image. Tied to a ~6-hour signing window (always at least 10 minutes of validity left); re-fetch the resource for a fresh one.
  - `prompt_used` string: The full prompt sent to the model — includes the aspect/resolution directive we append.
  - `aspect_ratio` '1:1' | '4:5' | '3:4' | '9:16' | '16:9' | '3:2' | '2:3'
  - `resolution` '1K' | '2K' | '4K'
  - `width` integer, nullable: Real width in pixels (if measured).
  - `height` integer, nullable
  - `created_at` string, date-time

## Other responses

- `400`: Missing file or project_id, or unsupported file type
- `401`: Missing or invalid token
- `402`: Storage quota exceeded
- `404`: Project not found
- `429`: Rate limit exceeded
- `500`: Unexpected server error while storing the file

---

[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)