---
title: "Import media from a URL (server-side fetch)"
method: POST
path: "/v1/media/import"
tags: ["media"]
---

# Import media from a URL (server-side fetch)

`POST /v1/media/import`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/media/import`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.cueframe.ai/api/auth/mcp/authorize`, token URL `https://api.cueframe.ai/api/auth/mcp/token`, scopes: `media:write`)
  - API key in header `PAYMENT-SIGNATURE`

Import media into the project from a public https URL — the server fetches and mirrors the bytes (SSRF-filtered), then processes video and audio. Async: returns a media id that flips to ready when the mirror and processing finish; poll GET /media/:id or use a media.completed webhook.

## Request body

- MediaImportRequest: POST /media/import body.
  - `url` string, uri, required
  - `filename` string, required
  - `contentType` 'video/mp4' | 'video/quicktime' | 'video/x-matroska' | 'video/webm' | 'audio/mpeg' | 'audio/wav' | 'audio/x-wav' | 'audio/mp4' | 'audio/aac' | 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif' | 'image/svg+xml' | 'application/json' | 'font/ttf' | 'font/otf' | 'font/woff' | 'font/woff2', required
  - `size` integer
  - `audioRole` 'vo' | 'music' | 'sfx' | 'ambience': Declared audio role: 'vo' (narration), 'music' (bed that ducks under speech), 'sfx' (one-shot hit), 'ambience' (a bed that HOLDS under VO — never ducks).

## Response `201`

Import enqueued.

- MediaImportResponse: POST /media/import response.
  - `id` string, required
  - `status` 'importing', required

## Other responses

- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).
- `403`: Forbidden — permission insufficient.
- `422`: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
- `429`: Rate limited. Retry-After header present.
- `500`: Internal error.
- `503`: Service unavailable — billing_unavailable / honest-503 for runtime deps.

---

[API](https://skmtc.dev/cueframe/apis/cueframe-api.md) · [All operations](https://skmtc.dev/cueframe/apis/cueframe-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cueframe/apis/cueframe-api/revisions/8f9bfe362b4a?raw)