# Import from a URL

`POST https://api.vidmoat.com/v1/media/import`

- Scope: `media.write`
- Cost: upload cap

Fetch a public http(s) URL server-side, up to your plan's upload cap or 512 MB, whichever is smaller. Destinations pass through the SSRF guard, so private ranges and metadata endpoints are refused.

### Body

- `url` (string, required): A public `http` or `https` URL to a video, image or audio file. Redirects are followed; the fetch times out after 120 seconds.

## Response

Returns `201`.

### Response fields

- `media` (object): The stored file.
  - `url` (string): Use as a clip `src`.
  - `filename` (string): Stored name.
  - `mediaType` (enum): What it is. One of `video`, `audio`, `image`.
  - `contentType` (string): MIME type.
  - `bytes` (integer): Size.
  - `durationSec` (number or null): Length, for video and audio.
- `hint` (string): What to do with it.

> **Tip: With a test key.** Test keys import for real.

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | No `url`, a private or unresolvable host, or a file that is not video, image or audio. |
| 413 | [`payload_too_large`](https://developer.vidmoat.com/developer/docs/errors#payload_too_large) | The file is larger than the import limit. |
| 502 | [`provider_error`](https://developer.vidmoat.com/developer/docs/errors#provider_error) | The URL could not be fetched (an upstream 404 or a timeout, for example). |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/media/import \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/clip.mp4"}'
```

```js Node
const res = await fetch('https://api.vidmoat.com/v1/media/import', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com/clip.mp4',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

res = requests.post(
    "https://api.vidmoat.com/v1/media/import",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "url": "https://example.com/clip.mp4",
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "media": {
    "url": "https://api.vidmoat.com/uploads/1727950000000-sample.mp4",
    "filename": "1727950000000-sample.mp4",
    "mediaType": "video",
    "contentType": "video/mp4",
    "bytes": 7340032,
    "durationSec": 14.2
  },
  "hint": "Pass `url` as `src` to addClip (type: \"video\", mediaDuration: 14.2)."
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/media/import-media
Previous: [Upload a file](https://developer.vidmoat.com/developer/docs/api/media/upload-media.md)
Next: [Search stock media](https://developer.vidmoat.com/developer/docs/api/media/search-stock.md)
All documentation: https://developer.vidmoat.com/llms-full.txt