Create a Media from URL

Creates a new media entry by importing a file from a public HTTPS URL. Swonkie fetches the file server-side and starts processing it immediately — no separate upload or confirmation step is needed.

This is a simpler alternative to the three-step POST /media → upload → PATCH /media/:mediaId flow. Use this endpoint when the file is already hosted at a publicly accessible URL.

Important: The URL must be publicly accessible over HTTPS without authentication. HTTP URLs, private/internal network addresses (e.g., 10.x.x.x, 192.168.x.x), and localhost are rejected to prevent server-side request forgery (SSRF). For videos, the file size is limited to 200 MB.

Notes

The URL must be a public HTTPS URL — HTTP, private IPs, and localhost are rejected.

Videos imported via URL are limited to 200 MB.

Processing starts immediately — no confirmation step is required.

The returned status will initially be PROCESSING. Poll GET /media/:mediaId until it becomes SUCCESS before using the media in posts.

path, preview, type, and specs will be null while processing is in progress.

destinationType determines how the media can be used: POST_MEDIA for regular post content, POST_LINK for link preview customization.

Media files remain in your library and can be reused across multiple posts.

curl --location 'https://api.swonkie.dev/v2/media/from-url' \ --header 'X-API-ID: ' \ --header 'X-API-KEY: ' \ --header 'Content-Type: application/json' \ --data '{ "name": "product-video.mp4", "destinationType": "POST_MEDIA", "fileUrl": "https://example.com/videos/product-launch.mp4" }'

{ "id": "TWVkaWFJZDk4NzY1NDMyMQ", "name": "product-video.mp4", "path": null, "preview": null, "type": null, "status": "PROCESSING", "specs": null, "createdAt": "2026-06-19T10:30:00.000Z" }

Create a Media from URL

Notes

Request

Responses

Create a Media from URL

Notes#

Request

Responses

Notes