MCP tools

An agent picks the tool from what you ask it to do. Each tool does the same work as the API endpoint beside it.

Every tool replies with JSON as text. A check replies with the same verdict POST /audit returns, described in Check an image. An optimization replies with the same job GET /optimize/{id} returns, and a video or voice check with the job GET /audit/{id} returns, as Check and optimize a video and Check a voice clip describe.

Wait for an optimizationCopy Anchor Link

An optimization usually takes longer than one tool call can wait. process_image starts the optimization and waits up to 45 seconds. process_video, audit_video and audit_audio wait the same way. If the optimization finishes in that time, the reply has the download link and the optimization score.

If it is still going, the reply carries the job's id, its status and a next field that tells the agent what to do. The agent calls get_processing_result with that id, which waits up to 45 seconds again. It repeats until the optimization succeeds or fails.

The optimization keeps running between calls, so the agent can come back to it later. Any key on your account can read the job, over MCP or with GET /optimize/{id}. Optimize an image covers the job's statuses and how long the download link lasts.

Send a local fileCopy Anchor Link

A file on disk goes through request_upload, so its bytes never pass through a tool call. Upload from an agent covers the steps and what to send when the agent cannot run commands.

Read tool errorsCopy Anchor Link

When realpng refuses a tool call, for example for too few credits, the agent gets an error result. Its text is the message the API sends for that error, without the code. Errors lists every one.

A wrong key, a plan without API access, a failed payment or going over requests a minute fails the whole request instead, before any tool runs. The agent then sees a failed request, not a tool error. Errors over MCP lists each one.

Tool referenceCopy Anchor Link

audit_imageCopy Anchor Link

Check an image and return an assessment for review within your image workflow. Includes a result, a score when available, and supporting check results. Pass exactly one of image_url, image_base64 or image_upload_id. Images up to 25 MB and 25 megapixels.

Input	Type	Required	Description
image_url	string, uri	No	Public http or https URL of an image up to 25 MB.
image_base64	string	No	The image as base64 or a data URL, up to 4 MB. Use request_upload for larger files.
image_upload_id	string, uuid	No	The id from request_upload, for a local file up to 25 MB already PUT to its upload_url. Preferred over image_base64 for a file on disk, since it avoids putting the image's bytes through this tool call.

request_uploadCopy Anchor Link

Get a one-time upload URL for a local image file up to 25 MB, or a video or voice clip up to 1 GB, so its bytes never pass through a tool call. Pass the file's exact size in bytes and its content type. PUT the raw bytes to upload_url yourself, once, with every returned header and a Content-Length (for example curl -T file -H "Content-Type: image/png" -H "If-None-Match: *" URL), then pass id as image_upload_id to audit_image or process_image, as video_upload_id to audit_video or process_video, or as audio_upload_id to audit_audio. The URL expires in 10 minutes and the upload is read once.

Input	Type	Required	Description
size	integer	Yes	The file's exact size in bytes, up to 25 MB for an image.
content_type	image/png, image/jpeg, image/webp, video/mp4, video/quicktime, video/webm, audio/mpeg, audio/wav, audio/x-wav, audio/mp4, audio/x-m4a	Yes	The file's content type.

process_imageCopy Anchor Link

Optimize an image for posting. Nothing is cropped. Optimizing typically takes about two minutes. This call waits up to 45 seconds. If it is still pending, pass the returned id to get_processing_result instead of submitting the image again. On success, returns an output image_url that works until expires_at and optimization_score, 100 minus our detectors' AI reading of the output, with its zone (high, good or low). Pass exactly one of image_url, image_base64 or image_upload_id. Images up to 25 MB and 25 megapixels.

Input	Type	Required	Description
image_url	string, uri	No	Public http or https URL of an image up to 25 MB.
image_base64	string	No	The image as base64 or a data URL, up to 4 MB. Use request_upload for larger files.
image_upload_id	string, uuid	No	The id from request_upload, for a local file up to 25 MB already PUT to its upload_url. Preferred over image_base64 for a file on disk, since it avoids putting the image's bytes through this tool call.

audit_videoCopy Anchor Link

Check a video and return an assessment for review, read on 8 frames spread through it. Includes a result, a score when available, supporting check results and each frame's reading. This call waits up to 45 seconds. If it is still pending, pass the returned id to get_processing_result instead of submitting the video again. Pass exactly one of video_url or video_upload_id. MP4, MOV or WebM up to 1 GB, 3 minutes and 5,400 frames (a 60 fps video stops at 90 seconds). Videos over 1920 px on the long edge are read at 1920 px. Costs 5 credits for every started 15 seconds. Pass seconds if you know the length: credits for it are held and a longer video is refused. Without it, credits for 3 minutes are held and the real length is charged.

Input	Type	Required	Description
video_url	string, uri	No	Public http or https URL of a video up to 1 GB.
video_upload_id	string, uuid	No	The id from request_upload, for a local video up to 1 GB already PUT to its upload_url. Preferred for a file on disk.
seconds	number	No	The video's length in seconds, if you know it.

audit_audioCopy Anchor Link

Check a voice clip for an AI voice and return an assessment for review, read in 4 second windows across the clip. Includes a result, a score when available, supporting check results and each window's reading. This call waits up to 45 seconds. If it is still pending, pass the returned id to get_processing_result instead of submitting the clip again. Pass exactly one of audio_url or audio_upload_id. MP3, WAV or M4A up to 1 GB and 3 minutes. Costs 5 credits for every started 15 seconds. Pass seconds if you know the length: credits for it are held and only that much of a longer clip is read. Without it, credits for 3 minutes are held and the real length is charged.

Input	Type	Required	Description
audio_url	string, uri	No	Public http or https URL of a voice clip up to 1 GB.
audio_upload_id	string, uuid	No	The id from request_upload, for a local voice clip up to 1 GB already PUT to its upload_url. Preferred for a file on disk.
seconds	number	No	The voice clip's length in seconds, if you know it.

process_videoCopy Anchor Link

Optimize a video for posting. Nothing is cropped and the sound is kept. Optimizing takes about as long as the video runs. This call waits up to 45 seconds. If it is still pending, pass the returned id to get_processing_result instead of submitting the video again. On success, returns an MP4 file_url that works until expires_at and optimization_score, 100 minus our detectors' AI reading of the output, with its zone (high, good or low). Pass exactly one of video_url or video_upload_id. MP4, MOV or WebM up to 1 GB, 3 minutes and 5,400 frames (a 60 fps video stops at 90 seconds). Videos over 1920 px on the long edge are read at 1920 px. Costs 20 credits for every started 15 seconds. Pass seconds if you know the length: credits for it are held and a longer video is refused. Without it, credits for 3 minutes are held and the real length is charged.

Input	Type	Required	Description
video_url	string, uri	No	Public http or https URL of a video up to 1 GB.
video_upload_id	string, uuid	No	The id from request_upload, for a local video up to 1 GB already PUT to its upload_url. Preferred for a file on disk.
seconds	number	No	The video's length in seconds, if you know it.

get_processing_resultCopy Anchor Link

Retrieve the status of an optimization, video check or voice check, waiting up to 45 seconds for completion. On success, an optimization returns its file_url and optimization_score, 100 minus our detectors' AI reading of the output, with its zone (high, good or low). A video or voice check returns its result. If the status is queued or running, call again with the same id. If the status is failed, review the returned error.

Input	Type	Required	Description
id	string, uuid	Yes	The id returned by process_image, process_video, audit_video or audit_audio.