# Check an image or a video

Checks one image for AI generation and answers with its verdict, score and lanes. A video or voice clip is a job: this answers 202 with its id, and GET /audit/{id} returns the verdict once it succeeds.

`POST https://realpng.com/api/v1/audit`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | `full` | No | full adds the raw engine report as detail. Its shape may change. |

## Request body

Exactly one of image_url, image_base64 or image_upload_id. image_url and image_upload_id take images up to 25 MB and 25 megapixels. image_base64 travels inside this request, so it is limited to 4 MB. Use POST /uploads for larger files.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `image_url` | string, uri | No | Public http or https URL on the default port, up to 25 MB |
| `image_base64` | string | No | Base64, or a data URL, up to 4 MB |
| `image_upload_id` | string, uuid | No | The id from POST /uploads, for a file already PUT to its upload_url |
| `video_url` | string, uri | No | Public http or https URL on the default port of an MP4, MOV or WebM up to 1 GB. Use POST /uploads for a large video. |
| `video_upload_id` | string, uuid | No | The id from POST /uploads, for a video already PUT to its upload_url |
| `audio_url` | string, uri | No | Public MP3, WAV or M4A URL up to 1 GB. |
| `audio_upload_id` | string, uuid | No | The id from POST /uploads, for a voice clip already PUT to upload_url |
| `seconds` | number | No | A video's or voice clip's length in seconds. Credits are held for it and a longer file is refused. Without it, credits for 3 minutes are held, and the real length is charged once the job finishes. |

## Responses

### 200

The verdict of an image

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `verdict` | `ai`, `real`, `uncertain`, `unavailable` | Yes |  |
| `score` | integer or null | Yes |  |
| `decided_by` | `watermark`, `provenance`, `pixels`, `weighed`, `conflict`, `voice` | Yes |  |
| `lanes` | object | Yes |  |
| `media` | `image`, `video`, `audio` | No |  |
| `video` | object | No |  |
| `audio` | object | No |  |
| `detail` | object | No | The raw engine report, only with detail=full |

### 202

A video or voice check, started

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string, uuid | Yes |  |
| `status` | `queued`, `running`, `succeeded`, `failed` | Yes |  |
| `media` | `image`, `video`, `audio` | Yes |  |
| `verdict` | `ai`, `real`, `uncertain`, `unavailable` | No |  |
| `score` | integer or null | No |  |
| `decided_by` | `watermark`, `provenance`, `pixels`, `weighed`, `conflict`, `voice` | No |  |
| `lanes` | object | No | As in Verdict |
| `video` | object | No |  |
| `audio` | object | No |  |
| `detail` | object | No | The raw engine report, only with detail=full |
| `error` | object | No | Once failed. Branch on code |

### 400

invalid_body: the body is not a JSON object. invalid_image: not exactly one file field, a malformed upload id, or an empty image. invalid_url: the URL is not a public http or https URL on its default port. image_unreachable, video_unreachable or audio_unreachable: the URL could not be fetched. audio_too_large: a voice clip over the byte cap. invalid_parameter: seconds is not a positive number.

### 401

invalid_key: the key is missing, malformed, unknown or revoked

### 402

plan_required: the plan has no API access. payment_failed: the last payment failed, update the card to resume. quota_exceeded: not enough credits left this period, with detail saying how many the call needs, how many are left and when they reset.

### 404

upload_not_found: nothing was uploaded to that id, or it was already used or expired. An upload is read once, by the first call that reaches the engine. A call refused before that (401, 402, 429, or 503 while the engine warms up) leaves it usable until it expires.

### 413

image_too_large: over 25 MB, or over 4 MB as image_base64. too_many_pixels: over 25 megapixels, with width, height and limit in detail. video_too_large: a video over 1 GB. video_too_long: seconds over 3 minutes, with seconds and max_seconds in detail.

### 415

unsupported_media: the file is not a supported image or video type, is animated, or cannot be decoded, or a check sends a video in an image field. video_unsupported: the video has no video stream that can be decoded. audio_unsupported: the voice clip cannot be read. unsupported_media on POST /optimize: voice clips can be checked, not optimized.

### 429

rate_limited: over the plan's requests a minute. too_many_jobs: over its jobs at once. Both carry Retry-After in seconds.

### 503

engine_unavailable: the engine is starting up, with Retry-After. model_unavailable: the detection models are not ready yet. uploads_unavailable: image storage is unavailable.

### default

A problem, with a stable code

Every error has a `code` and a `message`, listed on [Errors](/docs/errors).