library

Upload media from a host file reference

ChatGPT-only: attach a file ChatGPT holds, fetched server-side. DO NOT hand-call.

ChatGPT fills the file argument AUTOMATICALLY from the user's attachment or a generated image (its Apps SDK marks this argument as a file param) and passes a reference carrying a download_url. Marky downloads the bytes server-side and stores a durable copy — so it works even though ChatGPT's code sandbox blocks the outbound upload that create_media_upload needs. The returned original_url is the Marky-hosted link you feed to create_post / attach_media_to_file.

DO NOT select this tool yourself. If you are NOT ChatGPT — or you don't already have a real host-issued download_url for the file — use upload_media_from_url instead (when you have a URL), or create_media_upload (a local file when your runtime can make outbound web requests). There is no local-file access here, only a server-side fetch of the URL in file.download_url, so calling this without a genuine download_url just fails — don't invent one.

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 download_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-reference

Request

  • Base URL: https://api.mymarky.ai
  • URL: https://api.mymarky.ai/api/media/from-reference
  • 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.

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.