Prepare image & audio inputs
Encode the original file correctly and stay within the limits for your solution.
Send file contents, not a file path
Read the file on your server and encode its bytes as Base64. Put that string into the image, audio, background or images field required by your solution.
A local filename or an https image URL is not a supported file input. Raw Base64 and matching data URLs are supported. The short strings in JSON examples are placeholders, not valid images.
import { readFile } from "node:fs/promises";
const image = (await readFile("challenge.png")).toString("base64");Check decoded size and JSON size
Normal CAPTCHA images may be up to 100 KB. Other main image inputs and each drag-and-drop piece may be up to 600 KB. Grid instruction images may be up to 100 KB. Audio uses MP3, up to 1 MB.
Grid tiles must total 3 MB or less before encoding. The entire encoded JSON request must also fit within 5,000,000 bytes. Base64 increases the file size by roughly one third, so a file that fits its own limit can still make a combined request too large.
Image formats are JPEG, PNG and GIF. Keep grid images and tiles at or below 1000 px per side. Check the individual reference for any additional provider limits. Here, KB means 1,000 bytes.
Preserve ordering and dimensions
For a grid, send tiles from left to right across the first row, then the next row. The array length must equal rows multiplied by columns. Do not send both image and images.
For drag-and-drop, keep puzzle pieces in a stable order: each result entry corresponds to the same input array position. Coordinate and bounding-box results refer to the original image, not a resized preview.
Write a clear instruction
Describe the actual answer you need, for example: Select every tile containing a bus. Avoid instructions that contradict the image or ask for several unrelated actions.
Instructions accept up to 1000 characters after trimming. A grid can use comment, imgInstructions or both. The instruction image describes the target; it is not an extra tile.
Only send challenge content you are authorized to process. Do not include private account data, passwords or API keys in files or instructions.