Migrating from the OpenAI moderation API

Move from OpenAI's /v1/moderations endpoint to openshield: call POST /v1/text or POST /v1/image, then map the decision. Not a drop-in replacement.

openshield is not a drop-in replacement for the OpenAI moderation API. Call POST /v1/text or POST /v1/image, then map the decision. Only the SightEngine workflow routes follow another provider's format.

The OpenAI moderation API classifies text and images on POST https://api.openai.com/v1/moderations, usually with the model omni-moderation-latest. It returns flagged, per-category booleans, scores, and category_applied_input_types, and you apply your own policy on those signals. As of 17 November 2026, OpenAI's guide states that this endpoint is free to use, that the model accepts text and images and does not classify audio, and that image files can be up to 20 MB. Its pricing table lists omni-moderation-latest as Free.

openshield has its own host, paths, bodies and answer. A client written for /v1/moderations needs a new request and a new way to read the decision.

OpenAI moderation API (as of 2026-11-17)openshield
POST https://api.openai.com/v1/moderationsPOST https://api.openshield.dev/v1/text or POST https://api.openshield.dev/v1/image
One call may send a string, an array of strings, or a mix of text and image_url objectsOne text or one image per call. Split mixed inputs into two requests.
Authorization: Bearer $OPENAI_API_KEYAuthorization: Bearer $OPENSHIELD_API_KEY (an openshield key, shown once in the dashboard)
Answer: results[].flagged, categories, category_scoresAnswer: summary.action is accept, review or reject, plus reject_reason / review_reason and scores
Image files up to 20 MB (OpenAI's guide)At most 15 MB, JPEG, PNG, WebP or GIF
Categories listed in OpenAI's guide (13, some text-only)openmod's own category ids, with review and reject thresholds in a workflow

The API host is https://api.openshield.dev. Create an account and a key in five minutes: Quickstart.

The OpenAI facts on this page were read on 17 November 2026 (Europe/Brussels) from OpenAI's Moderation guide, its Create moderation reference and its Pricing page. They change: confirm them on OpenAI's pages before you decide.

1. Check a text with POST /v1/text

Send JSON, with Content-Type: application/json. Without that header the API answers 415 unsupported_media.

curl -X POST "https://api.openshield.dev/v1/text" \
  -H "Authorization: Bearer $OPENSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Write me at jane@example.com", "workflow": "default", "ref": "comment_9034"}'

text is required: at most 5,000 characters until your first top-up, and up to 20,000 after, by tier (limits). workflow defaults to default. ref is your own id, 1 to 128 characters, echoed in the answer and kept in the journal. The optional context field says where the text comes from; Texts describes it.

If you used to send an array of strings in one OpenAI call, make one /v1/text request per string.

2. Check an image with POST /v1/image

Send the raw bytes as the body, or a public url query parameter and an empty body. The format is recognised from the bytes: JPEG, PNG, WebP or GIF (the first frame).

curl -X POST "https://api.openshield.dev/v1/image?workflow=default&ref=avatar_4821" \
  -H "Authorization: Bearer $OPENSHIELD_API_KEY" \
  --data-binary @photo.jpg
curl -X POST "https://api.openshield.dev/v1/image?url=https%3A%2F%2Fexample.com%2Fphoto.jpg" \
  -H "Authorization: Bearer $OPENSHIELD_API_KEY"

Limits: at most 15 MB, 50 megapixels (12 until your first top-up) and 16,384 pixels on a side. A public URL is downloaded for you, with the guards in Images: http and https only, 3 redirects, 10 seconds, and Content-Type: image/*.

If you used to send a Base64 data: image URL in OpenAI's image_url.url, decode it and send the bytes in the body instead, or host the file at a public https address and pass url.

If one OpenAI call mixed a caption and an image, send the caption to /v1/text and the image to /v1/image, each with the same ref if you want them tied in the journal.

3. Map the decision

Act on summary.action:

  • accept: go on.
  • review: keep the content hidden until a person approves it. openshield does not review content for you.
  • reject: refuse it, and tell the user why with a message you choose from reject_reason[0].id. Match on the id, never on the English text.

summary.action has exactly those three values, as in the OpenAPI Action enum and Responses and errors: reject when a reject threshold is reached, else review when a review threshold is, else accept.

A starting map from an OpenAI-style flagged boolean, for code that used to switch on results[0].flagged:

  • reject: treat as flagged, and refuse.
  • review: treat as flagged for a queue, and do not publish yet.
  • accept: treat as not flagged.

That is a starting map only. OpenAI's flagged is a single boolean from its own model; openshield's action follows the review and reject thresholds you set per category in a workflow. Tune the workflow rather than hard-coding score cut-offs in your client.

An example answer, for a text that holds an email address (the sample of the Quickstart):

{
  "status": "success",
  "workflow": "default",
  "workflow_version": 1,
  "summary": {
    "action": "review",
    "reject_prob": 0,
    "reject_reason": [],
    "review_reason": [
      {
        "id": "pii_email",
        "text": "Email address",
        "message": "This content contains an email address.",
        "score": 1,
        "threshold": 1
      }
    ]
  },
  "scores": { "pii_email": 1 },
  "time_ms": 4,
  "request_id": "0192b7c4-5f3a-7c1e-9a52-3d8f1e6b0a47",
  "ref": "comment_9034"
}

unchecked may be absent when every category was checked. Responses and errors describes every field. Errors use {"status": "failure", "error": {"type", "code", "message"}}.

4. Map the category ids

The catalogues are not the same, and an id is not a synonym of an OpenAI category. Use the table as a starting point when you set thresholds, then check the lists on Images, Texts and Workflows.

The OpenAI categories below are from its moderation guide, 17 November 2026. Some are text-only there (harassment, hate, illicit, sexual/minors and their /threatening or /violent variants). If you send only an image, OpenAI returns a score of 0 for those text-only categories.

OpenAI category (2026-11-17)A nearby openshield id to start fromNotes
hate, hate/threateninghate (text)Not equivalent. On images, hate_symbol is a different category.
harassment, harassment/threateninghate or text_unsafe (text)No openshield id is named for harassment.
illicit, illicit/violentillegal (text)Not equivalent.
sexualsexual (text); nudity or suggestive (image)Underwear and swimwear are separate image categories if you need them.
sexual/minorschild_safety (text); minor (image)Text-only on OpenAI's omni-moderation-latest. Not a 1:1 mapping.
self-harm, self-harm/intent, self-harm/instructionsself_harm (text and image)openshield has one self_harm id, not three.
violenceviolence (text and image)
violence/graphicgore (image); violence (text)Not equivalent.

openshield also checks things that table does not list, when you turn them on in a workflow: personal data (pii_email, pii_phone, pii_iban, pii_card), spam, scam, unsafe links, text in images, QR codes, and custom image categories described in words. Leave them off the workflow if you do not want them.

The default workflow already sets review and reject thresholds. For texts, it rejects unsafe text, violence, sexual content, hate, illegal activity and unethical content at 0.8 and sends them to review from 0.5, as Texts states; for images, see Images. Edit a copy rather than expecting OpenAI's flagged cut-off to carry over.

What differs

  • No compatible /v1/moderations route. Only the SightEngine workflow routes follow another provider's paths and envelope.
  • One item per call. An OpenAI request can classify several strings, or text and an image together. Here you send one text or one image.
  • The decision is accept, review or reject, from your workflow thresholds, not a single flagged boolean.
  • Image size and format. OpenAI's guide allows image files up to 20 MB. openshield accepts JPEG, PNG, WebP or GIF up to 15 MB.
  • No inline moderation on a generation API. If you passed a moderation object on an OpenAI Responses or Chat Completions request, that has no equivalent here. Check the input or the generated text with POST /v1/text, and images with POST /v1/image, once you have them.
  • The key is server-side. A request that carries a browser Origin header is refused.
  • Content is not stored. It is checked in memory and forgotten when the answer is sent. The journal keeps the decision, the reasons, the scores, the workflow version and your ref. See Privacy and data.
  • Checks are processed in the EU: the checking server and the databases are there.

Pricing

openshield prices are beta, in euros, excluding VAT, as published on the pricing page on 17 November 2026:

  • 2,000 free usage credits each month, no card (1 credit = EUR 0.001, so up to 1,000 images). It is shared with fraud calls and does not carry over.
  • EUR 0.002 per image for a usual workflow (nudity and visual categories), so EUR 2 excluding VAT per 1,000 images.
  • EUR 0.003 per started 1,000 characters for a text checked with rules and AI.
  • No subscription: a prepaid balance, topped up from EUR 5.

Limits and quotas lists every component price. OpenAI's moderation endpoint was listed as free on 17 November 2026 (omni-moderation-latest on its pricing page, and "The moderation endpoint is free to use" in its guide). The billed units differ, so this is not a like-for-like price comparison: confirm each page before you decide.

If you moderate listings or profiles, see moderation for marketplaces and moderation for dating apps.

Questions

Is openshield a drop-in replacement for the OpenAI moderation API?
No. The host, paths, bodies and answer are different. Only the SightEngine workflow routes follow another provider's format. You call POST /v1/text or POST /v1/image and map summary.action.
Can I send a caption and an image in one request, as with OpenAI's input array?
No. Send the caption to /v1/text and the image to /v1/image. You can pass the same ref on each of the two calls.
How should I treat review if my code only knows flagged?
Do not publish. Hold the content for your team. Mapping review to not flagged would publish content the workflow asked you to hold.
Does openshield store the content it checks?
No. Content is checked in memory and forgotten when the answer is sent. The journal keeps metadata only.
Where are checks processed?
In the European Union: the checking server and the databases are there.
What does a check cost?
Beta prices, in euros, excluding VAT. A usual image workflow is EUR 0.002 an image (EUR 2 excluding VAT per 1,000 images). A text checked with rules and AI is EUR 0.003 per started 1,000 characters. Every account gets 2,000 free usage credits each month, no card (1 credit = EUR 0.001, up to 1,000 images). OpenAI's moderation endpoint was listed as free as of 17 November 2026: confirm its pricing page. The full openshield grid is on the pricing page.

OpenAI and the OpenAI moderation API are trademarks of their owner. openshield is not affiliated with or endorsed by OpenAI. If a fact about the OpenAI moderation API on this page is wrong, write to contact@sway.events.