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

# Upload media

> Upload an image or video to use in a post or message.

Upload a file, then choose whether to attach it once or save it in the Vault for reuse. Start the upload and send each part. Finalize the upload to mark it complete before creating content.

## Before you start

Ask the user to [authorize your app](https://docs.ofauth.com/v3/guides/link.md) with `vault:write`, which lets your app upload files. Use the returned token and select a linked account the user shared. Keep the original filename and file type, such as `image/png`.

Install the [TypeScript SDK](https://docs.ofauth.com/v3/sdk/typescript.md) version 4. Create a client on your server:

```typescript theme={null}
import { OFAuthClient, md5Hex } from "@ofauth/onlyfans-sdk"

const accessToken = process.env.ACCESS_TOKEN!
const linkedAccountId = process.env.LINKED_ACCOUNT_ID!
const client = new OFAuthClient({ accessToken, linkedAccountId })
```

Use this client for the rest of this guide. It sends the access token and linked account ID for API calls.

## Start an upload

Call `client.access.uploads.start()` with the original filename, size, file type, and MD5 hash. The SDK’s `md5Hex()` calculates the hash from the file bytes. The example below includes all four values.

The response has one of two statuses:

| Status | Result |
| - | - |
| `already_exists` | `media` contains an existing Vault item. Use `media.id`; no byte upload is needed. |
| `needs_upload` | `uploadId`, `uploadType`, `totalParts`, `partSize`, `expiresAt`, and `parts` tell you which parts to upload. |

Each part includes `partNumber`, `uploadUrl`, and `byteRange.start` and `byteRange.end`. Include the last byte in each range. Use the returned URL for each part.

![If creation returns already\_exists, use media.id. If it returns needs\_upload, PUT every returned byte range, finalize even a single-part upload, and use uploadId once.](https://mintcdn.com/ofauth/VVqOdSxbrh7mDF0M/images/v3/upload-paths.svg?fit=max\&auto=format\&n=VVqOdSxbrh7mDF0M\&q=85\&s=cc882d03c8e4fccb6e3faec44a342ad6)

If the file already exists, use its Vault media ID without uploading bytes. Finalize every new upload, even if it has only one part. To save the file for reuse, include the [Vault options](#keep-a-reusable-vault-id) when you finalize.

## Upload the parts and finish

Add this code after the client setup in a TypeScript file. Run it with the PNG path as its first argument. Set `ACCESS_TOKEN` and `LINKED_ACCOUNT_ID` in your environment. For another file type, change `contentType` to match, such as `image/jpeg`. The SDK starts and finalizes the upload. The `PUT` requests send the file bytes to the returned upload URLs.

```typescript theme={null}
import { readFile } from "node:fs/promises"
import { basename } from "node:path"

const filename = process.argv[2]!
const bytes = await readFile(filename)
const contentType = "image/png"
const file = {
	filename: basename(filename),
	size: bytes.length,
	contentType,
	etag: md5Hex(bytes)
}
const upload = await client.access.uploads.start({ body: file })

let mediaItem: number | string
if (upload.status === "already_exists") {
	mediaItem = upload.media.id
} else {
	for (const part of upload.parts) {
		const response = await fetch(part.uploadUrl, {
			method: "PUT",
			headers: {
				authorization: `Bearer ${accessToken}`,
				"x-linked-account-id": linkedAccountId,
				"content-type": contentType
			},
			body: bytes.subarray(part.byteRange.start, part.byteRange.end + 1)
		})
		if (!response.ok) throw new Error(await response.text())
	}
	await client.access.uploads.finalize({ body: { uploadIds: [upload.uploadId] } })
	mediaItem = upload.uploadId
}

console.log({ mediaItems: [mediaItem] })
```

Send raw bytes in each `PUT`. Do not wrap them in JSON, base64, or multipart form data. Keep the same bearer token and linked account headers for the upload URLs.

Finalization is required even for single-part uploads. `POST /v3/access/uploads/finalize` accepts 1 to 10 `uploadIds`. Without Vault options, it returns `{ "uploadIds": [...] }`. Use the completed upload reference in `mediaItems` when you create content.

## Keep a reusable Vault ID

To save the file in the Vault, use these finalization options in place of the finalization call above. Set `uploadId` to the new upload’s ID. Do not finalize the same upload twice:

```typescript theme={null}
const saved = await client.access.uploads.finalize({
	body: {
		uploadIds: [uploadId],
		vaultUpload: { userId: "123456", listId: 101 }
	}
})
if ("uploads" in saved) {
	console.log(saved.uploads.map(item => item.mediaId))
}
```

Use a valid target user ID for the linked account. `listId` is optional. Saving an upload in the Vault uses a temporary scheduled message. Its response contains `uploads`, each with `uploadId`, `mediaId`, and `media`, plus optional `listId` and `messageId`. Save `uploads[].mediaId` to use the file again. Optional `mediaIds` can include up to 10 existing IDs when adding the finalized media to a Vault list.

To upload several files, send `POST /v3/access/vault/uploads`. Include details for 1 to 10 files in `files`, along with the required `vaultUpload` options. Read batch status with `GET /v3/access/vault/uploads/:batchId`. See the [API reference](https://docs.ofauth.com/v3/api-reference.md) for each file’s status fields.

## Use the result

Use completed references in [posts](https://docs.ofauth.com/v3/guides/how-to/create-post.md), [messages](https://docs.ofauth.com/v3/guides/how-to/send-message.md), and [mass messages](https://docs.ofauth.com/v3/guides/how-to/mass-message.md). [Stories](https://docs.ofauth.com/v3/guides/how-to/create-story.md) accept exactly one non-GIF image.

A temporary upload reference works for one successful post, message, or story. You can reuse numeric Vault IDs. See [Media references](https://docs.ofauth.com/v3/guides/media-items.md).

## Recover from an interrupted upload

Save the start response and finish the upload before `expiresAt`. If a part fails, retry the same bytes at the same part URL before the upload expires. If you do not know whether a post, message, or story was created, check for it before trying again. Follow the response's [recovery instructions](https://docs.ofauth.com/v3/api-reference/errors.md).

At upload start, OFAuth checks the file hash and size for a matching Vault item. Use the returned parts and byte ranges for any new upload.


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