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

# Images and videos

> Media files are stored on our CDN, supporting file links, base64, file uploads, and on-the-fly image editing.

When your review includes image or video fields, we automatically stores the related [data from your request](/send-requests) on our CDN so they stay accessible throughout the review process and in any workflow steps after approval.

This is especially useful for AI-generated media, where source URLs from providers like OpenAI or Gemini can expire before your team finishes reviewing.

## Image URLs

An **image** field takes a URL string. gotoHuman downloads the file and stores a copy on our CDN.

```json theme={null}
{
  "data": {
    "heroImage": "https://files.oaiusercontent.com/file-somethingsomething?se=xyz"
  }
}
```

### Multiple images (list field)

To show several images, use a **list** field whose item template contains one **image** field.

**Scalar list** — each array element is an image URL:

```json theme={null}
{
  "data": {
    "candidateImages": [
      "https://files.oaiusercontent.com/file-one?se=xyz",
      "https://files.oaiusercontent.com/file-two?se=xyz"
    ]
  }
}
```

**Object list** — each row is an object with the image field id as a property:

```json theme={null}
{
  "data": {
    "candidates": [
      { "photo": "https://files.oaiusercontent.com/file-one?se=xyz" },
      { "photo": "https://files.oaiusercontent.com/file-two?se=xyz" }
    ]
  }
}
```

## Video URLs

A **video** field also takes a URL string. Videos are downloaded and cached on our CDN the same way as images.

```json theme={null}
{
  "data": {
    "previewVideo": "https://cdn.example.com/generated-clip.mp4"
  }
}
```

## Base64-encoded images

Send a base64 string as the image field value and set `isBase64` in that field's request config. Both raw base64 and data-URL form (`data:image/jpeg;base64,...`) are supported.

```json theme={null}
{
  "data": {
    "heroImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  },
  "config": {
    "fields": {
      "heroImage": {
        "isBase64": true
      }
    }
  }
}
```

For a **list** of base64 images, set `isBase64` under `listItemConfig` for the image child field (use the child field's id from your item template):

```json theme={null}
{
  "data": {
    "candidateImages": [
      "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
      "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    ]
  },
  "config": {
    "fields": {
      "candidateImages": {
        "listItemConfig": {
          "photo": {
            "isBase64": true
          }
        }
      }
    }
  }
}
```

<Info>
  Base64 images are replaced with the CDN URL when the request is ingested. URL-based images keep the original URL in `data` and expose the CDN URL via `fileCache` in the [response webhook](/webhooks) (see below).
</Info>

## File uploads (binary)

Upload binary files before creating a review request:

**Endpoint:** `https://api.gotohuman.com/uploadFiles`\
**Method:** `POST`\
**Headers:** `x-api-key: <your API key>`\
**Content-Type:** `multipart/form-data`

Upload files as form fields. Optionally include a `config` form field with image resize options (see [Image editing](#image-editing) below).

**Response:**

```json theme={null}
{
  "success": true,
  "files": [
    {
      "downloadURL": "https://cdn1.gotohuman.com/...",
      "originalName": "image.jpg",
      "size": 524288,
      "contentType": "image/jpeg"
    }
  ],
  "count": 1
}
```

Use the returned `downloadURL` values in your review request `data`. Maximum file size is 20 MB.

## Image editing

Apply on-the-fly **resizing** and **cropping** when images are cached. Use this when downstream steps (for example video generation from a reference image) or publish targets (for example social media) need a specific size or aspect ratio.

Pass resize options under `config.fields.<fieldId>.transform`:

```json theme={null}
{
  "data": {
    "heroImage": "https://www.imgs.com/img.jpg"
  },
  "config": {
    "fields": {
      "heroImage": {
        "transform": {
          "resize": {
            "width": 400,
            "height": 800,
            "fit": "cover"
          }
        }
      }
    }
  }
}
```

For a **list** of images, use the same `transform` shape under `listItemConfig` for the image child field:

```json theme={null}
{
  "data": {
    "candidateImages": [
      "https://www.imgs.com/img.jpg",
      "https://www.imgs.com/img2.jpg"
    ]
  },
  "config": {
    "fields": {
      "candidateImages": {
        "listItemConfig": {
          "photo": {
            "transform": {
              "resize": {
                "width": 400,
                "height": 800,
                "fit": "cover"
              }
            }
          }
        }
      }
    }
  }
}
```

**Resize options:**

* `width`, `height`: Target dimensions in pixels
* `fit`: How to fit the image — `cover`, `contain`, `fill`, `inside`, `outside`
* `position`: Position when using `cover` or `contain` — `top`, `right top`, `right`, `right bottom`, `bottom`, `left bottom`, `left`, `left top`, `centre`
* `background`: Background color for `contain` fit (e.g. `"#ffffff"`, `"red"`, `{r: 255, g: 0, b: 0, alpha: 1}`)
* `withoutEnlargement`: Boolean to prevent upscaling
* `withoutReduction`: Boolean to prevent downscaling

Resize applies to images only, not videos.

## CDN URLs in webhooks

When a review is completed, the [response webhook](/webhooks) includes your field values in `reviewResult.data`. For URL-based images and videos, the original URL is kept in `data` and the CDN URL is provided in a top-level `fileCache` map:

```json theme={null}
{
  "event": "review.completed",
  "reviewId": "123456abcdef",
  "reviewResult": {
    "response": "approved",
    "respondingUser": "[email protected]",
    "respondedAt": "2024-10-05T14:48:00.000Z",
    "data": {
      "heroImage": "https://files.oaiusercontent.com/file-somethingsomething?se=xyz",
      "candidateImages": [
        "https://files.oaiusercontent.com/file-one?se=xyz",
        "https://files.oaiusercontent.com/file-two?se=xyz"
      ]
    }
  },
  "fileCache": {
    "https://files.oaiusercontent.com/file-somethingsomething?se=xyz": "https://cdn1.gotohuman.com/...",
    "https://files.oaiusercontent.com/file-one?se=xyz": "https://cdn1.gotohuman.com/...",
    "https://files.oaiusercontent.com/file-two?se=xyz": "https://cdn1.gotohuman.com/..."
  }
}
```

Look up each original URL in `fileCache` to get the persistent CDN URL for approved workflow steps.