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

# Upload media from file

> Single multipart request: send the file plus workspace_id (optional folder_id). MIME type is detected from the file.

## Upload media from file

<Warning>
  **Do not call this on the standard API host.** Use **`https://upload.postsyncer.com/api/v1/media/upload/file`**, not `https://postsyncer.com/api/v1/...`. Same Bearer token as every other endpoint; only the **hostname** changes so large multipart uploads hit dedicated infrastructure ([overview](/api-reference/introduction)).
</Warning>

Upload **one** image or video with `multipart/form-data`. Fields:

* **`workspace_id`** (required) - workspace that will own the file
* **`file`** (required) - the binary upload
* **`folder_id`** (optional) - media library folder in that workspace

The API reads the **MIME type from the file** (you do not send `mimeType`). Allowed types are the same as in the app (JPEG, PNG, GIF, WebP, MP4, MOV, etc.). Maximum size per request is **500MB** (same as the in-app standard upload).

Response **`201`**: `{ "media": { "id", "url", "mime_type", ... } }` - use **`media.id`** in [Create post](/api-reference/posts/create) `content[].media`.

Do **not** use this endpoint for URL import - use [Import from URL](/api-reference/media/upload-url).

### Request

<ParamField body="workspace_id" type="integer" required>
  Workspace that will own the file
</ParamField>

<ParamField body="file" type="file" required>
  Image or video file
</ParamField>

<ParamField body="folder_id" type="integer">
  Optional media library folder id belonging to `workspace_id`
</ParamField>

### Example

<RequestExample>
  ```bash theme={null}
  curl -X POST "https://upload.postsyncer.com/api/v1/media/upload/file" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -F "workspace_id=12" \
    -F "file=@/path/to/photo.jpg"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "media": {
      "id": 1842,
      "name": "photo.jpg",
      "url": "https://…",
      "mime_type": "image/jpeg",
      "size": 240512,
      "is_processing": false,
      "type": "image",
      "ai_generated_id": null,
      "is_reference": false,
      "progress": 100,
      "alt": null
    }
  }
  ```
</ResponseExample>

Use on a post:

```json theme={null}
"content": [{ "text": "Hello", "media": [1842] }]
```

### See also

* [Media overview](/api-reference/media/overview)
* [Import from URL](/api-reference/media/upload-url)