Docs / Reference / API Reference

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:

MethodParameterRequest
Public URLurlGET or POST
File uploadmedia (audio for audio/check.json)POST encoded as multipart/form-data
Previously uploaded videomedia_idsee 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

EndpointDescription
check.jsonAnalyze 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.jsonApply a workflow (models and rules configured in the dashboard) to an image. Workflows
transform.jsonRedact or anonymize an image. Image redaction
feedback.jsonReport a misclassification. Feedback API
list/remove-item.jsonRemove an image from an image list. Image lists

Videos

EndpointDescription
video/check-sync.jsonAnalyze a short video and get the results in the response. Synchronous analysis
video/check.jsonAnalyze 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.jsonGet the status and results of a video job (GET), or stop it (DELETE). Interact with jobs
video/ongoing.jsonList ongoing video jobs. Interact with jobs
video/transform.jsonRedact 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.jsonCreate a signed URL to upload a large video, then analyze it with its media_id. Upload API

Text

EndpointDescription
text/check.jsonModerate a text with rules, ML models or both. Text moderation

Audio

EndpointDescription
audio/check.jsonDetect 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"
  }
}

FieldTypeDescription
statusstringsuccess or failure
request.idstringUnique id of the request. Include it when contacting support
request.timestampfloatUnix timestamp of the request
request.operationsintegerNumber of operations used by the request, see operations
model resultsobjectOne entry per model requested, described on each model page
media.idstringId of the analyzed media. For videos, this is the id used to get or stop the job
media.uristringThe 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"
  }
}

FieldTypeDescription
error.typestringThe category of the error, such as argument_error, media_error or usage_limit
error.codeintegerA code identifying the error. Include it with the request id when contacting support
error.messagestringA 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

ItemLimit
File size12 MB
Min dimensions8 pixels on at least one side (width or height)
Max dimensions64 megapixels (width × height)
Images per request6, with a total size of 24 MB, see batch processing

Videos

ItemLimit
File size50 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 streamsdepends on your plan: 1 on Free, 1 on Starter, 5 on Pro, custom on Enterprise

Audio

ItemLimit
File size20 MB

Text

ItemLimit
Length10,000 characters, 128 for usernames

Requests

ItemLimit
Request rateeach 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