---
title: "Import a video from a link"
method: POST
path: "/v1/videos/import"
tags: ["Videos"]
---

# Import a video from a link

`POST /v1/videos/import`

## Request

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

Brings in a video file from a public link, of any size your storage allows. The link is opened at once: a web page that plays a video (YouTube, Vimeo, a post) rather than the file itself, a dead link, or a file whose stated size does not fit your space is refused in this answer. Otherwise you get 202 with a `task_id` and the file streams into storage in the background; poll `/v1/tasks/{id}` until `status` is `complete`, when `generation_id` is the clip. A link that does not state its size is checked against your space as it arrives. When the project already holds the same file, the copy is dropped before it is counted and the task completes with the existing clip as `generation_id`.

## Request body

- object
  - `url` string, required: A direct link to the file (.mp4, .mov, .webm).
  - `project_id` string: Defaults to your most recently used project.
  - `name` string
  - `prompt` string: What the clip should be findable by.
  - `density` 'quick' | 'normal' | 'detailed': Index it for search (clips up to 180 s).
  - `metadata` object: A JSON object of your own fields (a quote number, a client, where it came from), at most 4 KB. Returned as `metadata` on every read.
  - `keep_original` boolean: Every clip gets a light 1080p H.264 editing copy, made in the background after the upload and counted toward your storage (none when the file already is 1080p H.264). `false` drops the uploaded original once the copy exists: it frees the space, and the clip is 1080p from then on (frames, downloads, exports).

## Response `202`

`task_id`, `status: "running"`, `project_id`, `name`, `size` (bytes, when the link states it)

## Other responses

- `400`: Not a link to a video file, an internal address, or the link failed
- `401`: Missing or invalid token
- `402`: Does not fit in your free space
- `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/b454211e598e?raw)