# How to upload media with the DunSocial API

> POST /api/media/upload-url for a presigned URL, PUT the raw file to it with the right Content-Type, then POST /api/media/complete to register the asset. Images are limited to 8 MB, video to 512 MB, & the resulting asset id goes into mediaUrls on a post.

Updated: 2026-10-05.

## The limits first

Media lives in the workspace gallery. These are the documented limits:

| Kind | Max size | Types |
|------|----------|-------|
| Images | 8 MB | jpeg, png, gif, webp |
| Video | 512 MB | mp4, quicktime, webm |

Media routes need a bearer token & the workspace header. Reading needs `media:read` & uploading needs `media:write`.

## Step 1: get an upload URL

```bash
curl -X POST https://api.dunsocial.com/api/media/upload-url \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "hero.jpg",
    "mimeType": "image/jpeg",
    "fileSize": 245760
  }'
```

The response gives you `uploadUrl`, `storageKey` & `expiresAt`.

## Step 2: PUT the file

Send the raw file bytes to `uploadUrl` with the correct `Content-Type`:

```bash
curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @hero.jpg
```

The bytes go to the presigned storage URL, not to the API server, which is why this is a separate step.

## Step 3: complete the upload

Confirm it so the file appears in the gallery:

```bash
curl -X POST https://api.dunsocial.com/api/media/complete \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "storageKey": "STORAGE_KEY",
    "originalFilename": "hero.jpg",
    "mimeType": "image/jpeg",
    "fileSize": 245760,
    "altText": "Product screenshot"
  }'
```

It returns 201 with the asset & a preview URL. For video, include `width`, `height` & `duration`, since some platforms need them. Duration is stored in milliseconds, & values under 1,000 are treated as seconds & converted.

DunSocial only adds the file to the gallery once this call succeeds, so an abandoned upload leaves nothing behind.

## Use the asset on a post

Take the asset id from the response & pass it in `mediaUrls` when you schedule. DunSocial keeps asset ids on stored posts, so the same asset can be reused across many posts.

You can also check an asset against a platform before using it: `GET /api/media/validate?mediaAssetId=...&platform=...` returns `valid` & any issues.

## Alt text

Add `altText` when you complete the upload, or later with `PATCH /api/media/:id/alt-text`. DunSocial stores it on the asset, so it travels with the image wherever it's used.

## Deleting

`DELETE /api/media/:id` removes an asset. It fails with a 400 if a published post still uses it, or if it's scheduled & you didn't pass `forceDeleteScheduled`.

Check `GET /api/media/:id/relationships` first to see which posts & drafts use an asset & whether it can be deleted.

DunSocial's relationships route is there to stop you deleting something a post still depends on.

## Related guides

- [How to schedule a post with the DunSocial API](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-schedule-a-post-with-the-dunsocial-api.md)
- [How to attach images & videos to a post from the DunSocial CLI](https://www.dunsocial.com/hub/dunsocial-cli-guides/how-to-attach-images-and-videos-to-a-post-from-the-dunsocial-cli.md)
- [What platform options does the DunSocial API require?](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/what-platform-options-does-the-dunsocial-api-require.md)
- [What social media content formats actually work?](https://www.dunsocial.com/hub/social-media-content-creation/what-social-media-content-formats-actually-work.md)

## About this document

This is the Markdown representation of https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-upload-media-with-the-dunsocial-api. The HTML version of the same page is at the same URL. You can also request Markdown from any page by sending `Accept: text/markdown`.

Machine-readable summary of the whole site: https://www.dunsocial.com/llms.txt

## Company

- Product: DunSocial, https://www.dunsocial.com
- Legal entity: THISUX PRIVATE LIMITED, Chennai, Tamil Nadu, India
- Support: support@dunsocial.com
- Open the app: https://app.dunsocial.com/login