API Reference
How requests to the Sightengine API are made: base URL, authentication, how to send media, the list of endpoints, the response format, operations and limits.
Base URL
All API endpoints are served over HTTPS under:
https://api.sightengine.com/1.0/
Some Enterprise accounts are given access to another domain, such as a regional domain. If this is your case, use the domain provided with your account in place of api.sightengine.com. The paths are the same.
Requests are stateless. Each request carries its credentials, the media (or text) to analyze, and the list of models to apply with the models parameter. Several models can be combined in one request by separating them with commas, for instance models=nudity-2.1,gore-2.0. The model names are listed on each model page, see visual models and text moderation.
Authentication
The API authenticates requests with a key pair made of an API user and an API secret. To get yours, create an account and open the API keys page of the dashboard.
Send them with every request as the api_user and api_secret parameters, in the query string or in the form data.
Your API secret gives access to your account and usage. Keep it on your servers: do not embed it in mobile apps, browser code or public repositories.
Sending media
Images, videos and audio files can be submitted in three ways:
| Method | Parameter | Request |
| Public URL | url | GET or POST |
| File upload | media (audio for audio/check.json) | POST encoded as multipart/form-data |
| Previously uploaded video | media_id | see the Upload API, for videos too large to send in one request |
When you send a URL, the API downloads the media itself. The URL must:
- start with http:// or https:// and use the default port (80 or 443)
- be publicly reachable, with no authentication
- point to the final location of the file: redirects (3xx responses) are not followed
- be properly URL-encoded, without spaces
- not point to a private or reserved address such as localhost
Text is sent as a string in the text parameter, see the text moderation introduction.
Image files can be JPEG, PNG, WebP, GIF, AVIF and other common formats. Animated images such as GIFs are analyzed on a sample of their frames.
Endpoints
Paths are relative to the base URL. Each endpoint is described in detail on the linked page.
Images
| Endpoint | Description |
| check.json | Analyze an image with one or more models: moderation, AI-generated image and deepfake detection, faces, OCR, quality... Also used to add images to and search image lists. Quick start, batch processing |
| check-workflow.json | Apply a workflow (models and rules configured in the dashboard) to an image. Workflows |
| transform.json | Redact or anonymize an image. Image redaction |
| feedback.json | Report a misclassification. Feedback API |
| list/remove-item.json | Remove an image from an image list. Image lists |
Videos
| Endpoint | Description |
| video/check-sync.json | Analyze a short video and get the results in the response. Synchronous analysis |
| video/check.json | Analyze a longer video or a live stream, results sent to your callback URL. Asynchronous analysis, live streams, callbacks |
| video/check-workflow-sync.json video/check-workflow.json | Same as above, with a workflow. Video workflows |
| video/byid.json | Get the status and results of a video job (GET), or stop it (DELETE). Interact with jobs |
| video/ongoing.json | List ongoing video jobs. Interact with jobs |
| video/transform.json | Redact or anonymize a video. Video redaction |
| video/add-to-list.json video/check-list.json | Add a video to a video list, or search a list for near-duplicates. Video lists |
| upload/create-video.json | Create a signed URL to upload a large video, then analyze it with its media_id. Upload API |
Text
| Endpoint | Description |
| text/check.json | Moderate a text with rules, ML models or both. Text moderation |
Audio
| Endpoint | Description |
| audio/check.json | Detect AI-generated speech and music in an audio file. AI speech, AI music |
Audio moderation of speech (profanity, harmful content) runs on video files and audio tracks through video/check-sync.json, see the audio moderation model.
Responses
All responses are JSON objects. A successful image request returns:
{
"status": "success",
"request": {
"id": "req_0zrbHDeitGYY7wEGncAne",
"timestamp": 1491402308.4762,
"operations": 2
},
"nudity": { ... },
"gore": { ... },
"media": {
"id": "med_0zrbk8nlp4vwI5WxIqQ4u",
"uri": "https://example.com/image.jpg"
}
}
| Field | Type | Description |
| status | string | success or failure |
| request.id | string | Unique id of the request. Include it when contacting support |
| request.timestamp | float | Unix timestamp of the request |
| request.operations | integer | Number of operations used by the request, see operations |
| model results | object | One entry per model requested, described on each model page |
| media.id | string | Id of the analyzed media. For videos, this is the id used to get or stop the job |
| media.uri | string | The URL or file name of the analyzed media |
Failed requests return a different body, described in errors.
Errors
When a request fails, the API returns an HTTP status in the 4xx or 5xx range, "status": "failure" and an error object:
{
"status": "failure",
"request": {
"id": "req_jBS589QCnfWJmBKFZ1z71",
"timestamp": 1763657604.988901,
"operations": 0
},
"error": {
"type": "credentials_error",
"code": 1,
"message": "Incorrect API user or API secret"
}
}
| Field | Type | Description |
| error.type | string | The category of the error, such as argument_error, media_error or usage_limit |
| error.code | integer | A code identifying the error. Include it with the request id when contacting support |
| error.message | string | A human-readable explanation, usually with the fix |
Most errors come from the request or the media (4xx statuses): read error.message, fix the request and send it again. A 429 status means the request was throttled, see limits. A 5xx status is a problem on our side: wait and retry.
For all error types, the most common error codes and when to retry, see error codes and responses.
Operations
Usage is counted in operations. The request.operations field of each response gives the number of operations that request used. Requests that fail with an error use no operation.
The number of operations depends on the models and the media: most image models use 1 operation per image, some advanced models use more, and videos are counted per analyzed frame. Your plan's quota and current usage are shown in the dashboard, and plans are listed on the pricing page.
Limits
Images
| Item | Limit |
| File size | 12 MB |
| Min dimensions | 8 pixels on at least one side (width or height) |
| Max dimensions | 64 megapixels (width × height) |
| Images per request | 6, with a total size of 24 MB, see batch processing |
Videos
| Item | Limit |
| File size | 50 MB for files sent in the request. Up to 500 MB for files sent through the Upload API, on plans that include it (see pricing) |
| Video duration (sync requests) | 60 seconds |
| Video duration (async requests) | 30 minutes by default, up to 60 minutes on Starter and Pro plans with the max_duration parameter (in seconds). Longer limits are available on Enterprise plans: contact us |
| Concurrent jobs and streams | depends on your plan: 1 on Free, 1 on Starter, 5 on Pro, custom on Enterprise |
Audio
| Item | Limit |
| File size | 20 MB |
Text
| Item | Limit |
| Length | 10,000 characters, 128 for usernames |
Requests
| Item | Limit |
| Request rate | each account has a maximum number of requests and operations per second. Above it, the API returns an HTTP 429 error with type usage_limit and code 33. Spread out requests, or contact us for a higher limit |