Migrating from SightEngine

openshield serves three SightEngine workflow routes. A client written for them needs three changes. Only these routes are served: SightEngine's other endpoints, such as /1.0/check.json, are not.

The base URL is https://api.openshield.dev.

1. Point the client at the new base URL

curl -X POST "https://api.openshield.dev/1.0/check-workflow.json" \
  -F "media=@photo.jpg" \
  -F "workflow=default" \
  -F "api_user=ignored" \
  -F "api_secret=$OPENMOD_API_KEY"

curl "https://api.openshield.dev/1.0/check-workflow.json?url=https%3A%2F%2Fexample.com%2Fphoto.jpg&workflow=default&api_user=ignored&api_secret=$OPENMOD_API_KEY"

curl -X POST "https://api.openshield.dev/1.0/text/check-workflow.json" \
  -F "text=Write me at jane@example.com" \
  -F "workflow=default" \
  -F "api_user=ignored" \
  -F "api_secret=$OPENMOD_API_KEY"

For an image, send either media (the file) or url (a public address, downloaded for you, with the same guards). The GET form takes url only, as a query string cannot carry a file.

The whole form must arrive within 10 seconds (408 request_timeout otherwise), and every field but media is limited to 64 KB. A text field holds up to the 20,000 characters of a text check (5,000 on the free plan).

2. Create the workflows you used

A SightEngine workflow is named in your calls. Create a workflow of the same name in the dashboard, or use default. The new workflow decides what is checked and how strictly: start from a template and adjust the thresholds.

3. Map the category ids

The answer carries the fields of a SightEngine workflow answer: status, request (id, timestamp as a float of seconds, operations), workflow ({"id": "<name>"}), summary.action, summary.reject_prob and summary.reject_reason, plus summary.review_reason. Errors carry request too. The categories are openmod's own: match on reject_reason[].id and never on the English text. Map each id to the message you show your users.

The ids you are most likely to meet are nudity, gore, weapon, hate_symbol, self_harm, drugs and minor for images, and text_unsafe, violence, sexual, hate, illegal, unethical, self_harm, pii_email, pii_phone, pii_iban, pii_card, spam, scam and link_unsafe for texts. Workflows lists where to see all of them.

What differs

• SightEngine's per-model score fields at the top level of the answer (such as weapon, alcohol or drugs) are not served. The scores are in scores, keyed by openmod's category ids, and reject_reason[].text is openmod's wording.
• SightEngine's models and their other fields (faces, text in images, quality and the rest) are not served: a workflow here runs openmod's own categories.
• The answer also carries openmod's own fields: request_id, workflow_version, scores, time_ms and ref. A client may ignore them. request.operations is 1 for a check and 0 for a refusal.
• The routes accept an optional ref field to attach your own id to a check; the /v1 routes are the documented way to do it.
• Errors use the openmod envelope: {"status": "failure", "error": {"type", "code", "message"}}.
• The key is secret and server-side: a request that carries an Origin header is refused.

Sightengine is a trademark of its owner; openshield is not affiliated with it.