mediaItems selects the files to attach to a post, message, or story. Use a Vault ID, a completed upload reference, or an allowed URL. Use the formats below exactly. Do not send plain text, processing objects, objects such as { id: ... }, or file bytes.
Supported values
Story creation requires exactly one item. It rejects GIFs and videos, even though posts and messages can accept them.
Attach existing media
Attach a completed upload
mediaItem value from Upload media. With the SDK’s upload-start response, use media.id for already_exists or the completed uploadId for needs_upload. Upload every part, then finalize the upload to mark it complete. Use the same authorization and linked account when you create the content. An upload reference does not work for another account or authorization.
A temporary upload reference works for one successful post, message, or story. To use the file again, start a new upload or save it in the Vault during finalization. You can reuse a numeric Vault ID. The API rejects references that have expired, do not exist, or are not ready.
Attach a remote URL
For posts and messages, a public HTTP or HTTPS URL can be mixed with Vault IDs:Put free previews first
For paid posts and messages,previewMediaCount sets how many attachments at the start of mediaItems are free previews. Keep previews first and paid content after them. For example, mediaItems: [789, 790, 791] with previewMediaCount: 1 produces this order:
mediaItems determines whether it is free. Its ID does not. previewMediaCount is not a story input.
For a story, crop, rotate, or arrange the image before uploading it. The story request accepts mediaItems and optional releaseForms. It has no image editor settings.