media.md 1.7 KB
Newer Older
Eugen Rochko's avatar
Eugen Rochko committed
1
---
2
title: Media attachments
Eugen Rochko's avatar
Eugen Rochko committed
3 4
menu:
  docs:
5
    parent: rest-api
Eugen Rochko's avatar
Eugen Rochko committed
6 7
    weight: 10
---
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46

## POST /api/v1/media

Upload a media attachment that can be used with a new status.

Returns [Attachment]({{< relref "entities.md#attachment" >}})

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="write write:media" version="0.0.0" >}}

### Parameters

|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `file` | Media to be uploaded (encoded using `multipart/form-data`) | Required ||
| `description` | A plain-text description of the media for accessibility (max 420 chars) | Optional ||
| `focus` | Two floating points, comma-delimited. See [focal points](#focal-points) | Optional ||

## PUT /api/v1/media/:id

Update a media attachment. Can only be done before the media is attached to a status.

Returns [Attachment]({{< relref "entities.md#attachment" >}})

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="write write:media" version="0.0.0" >}}

### Parameters

|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `description` | A plain-text description of the media for accessibility (max 420 chars) | Optional ||
| `focus` | Two floating points, comma-delimited. See [focal points](#focal-points) | Optional ||

## Focal points

Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. [See this for how to let users select focal point coordinates](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point).