> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Media references

> Choose media IDs, completed uploads, or URLs for attachments

`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

| Value | Posts and messages | Story creation |
| - | - | - |
| Positive numeric Vault ID, such as `789` | Supported | Supported for an image |
| Numeric string, such as `"789"` | Supported | Supported for an image |
| Completed `upload:` reference | Supported | Supported for a non-GIF image |
| Public HTTP or HTTPS media URL | Supported with restrictions below | Rejected |
| Processing object or other text | Rejected | Rejected |

Story creation requires exactly one item. It rejects GIFs and videos, even though posts and messages can accept them.

## Attach existing media

```json theme={null}
{
	"text": "New set",
	"mediaItems": [789, "790"]
}
```

Choose IDs from the selected account's [Vault](https://docs.ofauth.com/v3/guides/media.md). Vault IDs can be reused in multiple posts or messages.

## Attach a completed upload

```json theme={null}
{
	"text": "New upload",
	"mediaItems": ["upload:550e8400-e29b-41d4-a716-446655440000"]
}
```

Use the `mediaItem` value from [Upload media](https://docs.ofauth.com/v3/guides/how-to/upload-media.md). 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:

```json theme={null}
{
	"text": "Preview and new image",
	"mediaItems": [789, "https://cdn.example.com/photo.jpg"]
}
```

OFAuth downloads the file from the URL. It must return an image, video, or audio file without a login or your app’s authentication headers. The file can be up to 5 MiB. The URL can redirect up to five times. Private or blocked hosts are rejected. For larger files, use [Upload media](https://docs.ofauth.com/v3/guides/how-to/upload-media.md), which splits files into parts.

## 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:

![In this example, item 789 is the free preview, followed by items 790 and 791 that require purchase. Preserve the order of mediaItems.](https://mintcdn.com/ofauth/VVqOdSxbrh7mDF0M/images/v3/preview-order.svg?fit=max\&auto=format\&n=VVqOdSxbrh7mDF0M\&q=85\&s=10888c0e3a72f18518bca4c5c3a010f7)

The attachment’s position in `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.