# Uploading images

Upload photos, and use them for a new artwork or to back up a change.

Images in a suggestion need to be on Street Art Cities. That goes for an artwork's photos (`images`), and for images that back up a change (`editAttachments`). Upload them in two steps, then use the link you get.

## 1. Get an upload link

```bash
curl "https://streetartcities.com/api/media/upload?filename=big-cat.jpg&contentType=image/jpeg" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

| Parameter     | Value                                       |
| ------------- | ------------------------------------------- |
| `filename`    | The file's name, ending in `.jpg` or `.png` |
| `contentType` | `image/jpeg` or `image/png`                 |

```json
{
  "key": "media/3/3f2c9a1e-…/orig.jpg",
  "url": "https://…amazonaws.com/media/3/3f2c9a1e-…/orig.jpg?X-Amz-…",
  "publicUrl": "https://streetartcities.com/media/3/3f2c9a1e-…/orig.jpg"
}
```

`url` is where you upload the file. It works for 15 minutes. `publicUrl` is where the image will be.

## 2. Upload the file

Send the file to `url` with a `PUT`, and the same `Content-Type` you asked for:

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

Only upload JPG and PNG photos, up to 25 MB. Soon after, we make smaller versions of it, next to the original: `512.jpg`, `1024.jpg` and `2048.jpg`.

## 3. Use the image

**As a photo of an artwork**, add it to `images`, when [adding a new artwork](/edits-api/suggesting-changes/#adding-a-new-artwork):

```json
"images": [
  {
    "id": "0b6e1c2d-5f4a-4e8b-9c3d-2a1f0e9d8c7b",
    "url": "https://streetartcities.com/media/3/3f2c9a1e-…/orig.jpg",
    "sizes": {
      "small": "https://streetartcities.com/media/3/3f2c9a1e-…/512.jpg",
      "medium": "https://streetartcities.com/media/3/3f2c9a1e-…/1024.jpg",
      "large": "https://streetartcities.com/media/3/3f2c9a1e-…/2048.jpg"
    },
    "attribution": "Jane"
  }
]
```

| Field         | Value                                                                                           |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `id`          | A new, random UUID for each image                                                               |
| `url`         | The `publicUrl`                                                                                 |
| `sizes`       | The same link, with `orig.jpg` (or `orig.png`) swapped for `512.jpg`, `1024.jpg` and `2048.jpg` |
| `attribution` | Who took the photo. We show it on the artwork                                                   |

The first image is the main one. To add a photo to an existing artwork, use `"images": { "$add": [{ … }] }`.

**To show as a comment attachment**, add the `publicUrl` to `editAttachments`:

```json
{
  "entityType": "marker",
  "entityId": "9ff36a03-…",
  "actions": { "status": "removed" },
  "editComment": "It's been painted over",
  "editAttachments": ["https://streetartcities.com/media/3/3f2c9a1e-…/orig.jpg"]
}
```