Skip to main content
When your review includes image or video fields, we automatically stores the related data from your request 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. 
{
  "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: 
{
  "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: 
{
  "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. 
{
  "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. 
{
  "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): 
{
  "data": {
    "candidateImages": [
      "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
      "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    ]
  },
  "config": {
    "fields": {
      "candidateImages": {
        "listItemConfig": {
          "photo": {
            "isBase64": true
          }
        }
      }
    }
  }
}
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 (see below).

​
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 below). Response: 
{
  "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: 
{
  "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: 
{
  "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 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: 
{
  "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.