library

Upload media (from URL)

Add an image or video to a business's MEDIA library by giving Marky a URL to fetch.

PREFER THIS whenever the media has any http(s) URL (a generated-image output URL, a web image, a CDN or file-host link). It is the simplest, most reliable path: Marky downloads it server-side, so it works even when your runtime can't make outbound requests. Only reach for create_media_upload (a local file AND your runtime has outbound network) or upload_media_from_reference (ChatGPT only, auto-filled) when you do NOT have a URL. Pass the http(s) URL; we store a durable copy. Private and internal addresses (and redirects to them) are rejected.

Send an Idempotency-Key header to make a retry safe (a resend that fetches the same bytes returns the original media asset instead of a duplicate).

Supported formats: JPEG, PNG, WebP, GIF, MP4, MOV. Images are automatically optimized. Max size: 20 MB for images, 500 MB for video.

Errors: 400 invalid_value: The business_id is not a valid UUID, the URL is not fetchable (bad scheme, private address, HTTP error), or the content is not a supported image or video. 401 authentication_required: API key or token is missing, invalid, or revoked. 403 permission_denied: Your plan does not include API access, or this business is not in your org. 404 resource_not_found: No business with that ID exists. 413 FILE_TOO_LARGE: The fetched media is larger than the size limit. 422 IDEMPOTENCY_KEY_CONFLICT: The Idempotency-Key was reused with a different body. 429 rate_limit_exceeded: You sent too many requests this minute.

post/api/media/from-url

Request

  • Base URL: https://api.mymarky.ai
  • URL: https://api.mymarky.ai/api/media/from-url
  • Auth: HTTP bearer

Headers

Idempotency-Keystring nullable

Optional. Send a unique value (e.g. a UUID) to make this create request safe to retry. A repeat with the same key returns the original response instead of creating a duplicate. Cached for 24h, scoped to your org. Reusing a key with a different body returns 422.

Marky-Version'2026-04-08' | '2026-07-17' | '2026-08-02' | '2026-08-04' | '2026-08-06'
Example:2026-08-06

Opt into a dated API version. Omit to stay on the floor (2026-04-08) forever — unpinned clients never break. Pin to a newer date (e.g. 2026-08-06) to receive the newest response shapes. Unknown values fall back to the floor. See https://docs.mymarky.ai for the versioning model.

Request body

business_idstring required

UUID of the business to upload the media into. Get it from list_businesses. Must belong to the API key's org.

urlstring required

Public http(s) URL of the image or video to fetch. Private and internal addresses are rejected. Max size: 20 MB for images, 500 MB for video.

filenamestring nullable

Optional original filename (e.g. clip.mp4). Helps detect video when the URL path and server content type don't make it obvious.

alt_textstring nullable

Optional hint about the media: an address, a name, anything the picture can't show. Stored as source_alt_text; alt_text is written by looking at the image itself shortly after upload.

Response

Successful Response

idstring required

Media ID

business_idstring required

Business this media belongs to

alt_textstring nullable

Alt text description

original_urlstring nullable

Media URL

typestring nullable

Media type: image, video, or audio

widthinteger nullable

Width in pixels

heightinteger nullable

Height in pixels

sourcestring nullable

Media origin (e.g. upload, unsplash)

created_atstring required

When the media was uploaded

source_alt_textstring nullable

The alt_text you sent, kept as a hint. alt_text is written a few seconds after upload by looking at the image itself, so it is empty in this response. Search results show that description.

Changes

No recorded changes to this operation across all 1 revision of this API.