Poyo's free image moderation API helps you assess profile photos, community pictures, and product uploads before deciding how to publish them. With Omni Moderation, you can review one image on its own or include its caption in the same request.
Start in the Playground to see category flags and scores for your own examples. Then use Poyo's task tracking and optional completion callback to connect those results to your application's publishing rules and review tools.
This guide explains the supported image categories, how to prepare an upload, and how to build a clear path from submission to publication or further review. You can apply the process to one upload surface first, then expand it as your team gains experience.
What image moderation should do for your product
Start with the place where images appear and who will see them.
An avatar can be visible beside every comment. A community photo may appear in a public feed. A product image may sit beside a listing that needs checks beyond visual safety. Each surface can require different rules and a different level of caution before publication.
For example, a product might accept a non-graphic historical image inside a discussion while declining it as a profile photo. The image has not changed; its placement and the product's rules have.
Write down what should happen for three outcomes: the image meets the rules, its meaning is unclear, or it clearly violates a rule. Also define a fourth outcome for an unavailable assessment. A processing error should not be silently interpreted as an approval.
What Omni Moderation checks in images
Poyo gives you zero-credit access to six image risk categories covering sexual content, violence, and self-harm. Each request accepts one HTTPS image URL; add a caption to assess the supplied text alongside the picture.
| Category | What the signal concerns |
|---|---|
sexual | Sexual content |
violence | Violence |
violence/graphic | Graphic violence |
self-harm | Self-harm content |
self-harm/intent | Indications of self-harm intent |
self-harm/instructions | Self-harm instructions |
Use category_applied_input_types to see whether a result applies to the image, the supplied text, or both. Text input supports 13 categories, including hate, harassment, illicit instructions, and sexual/minors. Those text-only categories assess supplied text; they are not image checks. For an image-only request, a zero score and an empty input-type list for an unsupported category mean it was not assessed.
For rules that depend on words embedded in a picture, add a suitable text-extraction step and review the extracted text. Product quality, watermarks, personal information, and prohibited-item rules also need their own checks. Video and animated uploads require a separate frame-selection workflow, and audio requires separate processing; reviewing selected frames does not assess a whole video or its soundtrack.
Omni Moderation is not a dedicated CSAM detector, and sexual/minors supports text only. Do not submit known or suspected CSAM to OpenAI's Moderation API; follow the official child-safety guidance.
The Poyo API documentation describes the supported inputs and response fields. Use this coverage to choose the checks for each upload surface.
Prepare the upload before requesting a review
Your application needs an image resource the moderation service can fetch. A filename such as photo.jpg on a user's device is not sufficient, and a webpage showing an image is not necessarily the image URL.
Keep new uploads outside public feeds while the review is pending. This staging area can be part of your existing storage system. Apply access controls, and choose a supported delivery method that lets the service retrieve the specific file without exposing your whole storage account.
If that method uses a temporary HTTPS URL, allow enough time for queued processing and retries. Do not include session credentials in the URL, and avoid putting private image links in broadly accessible logs.
Validate the upload before sending it for content assessment. Check that it is an expected file type and can be decoded, and apply file-size and image-dimension limits suitable for your application and provider. Those are upload checks; a moderation score does not validate a file's technical safety.
Record a stable content ID and version. Associate the task ID with that version so a result cannot accidentally approve an image the user replaced while review was running.
A practical upload-to-publish workflow
A simple process can work without a large moderation team, provided the states and responsibilities are explicit.
| Stage | What happens | What the user sees |
|---|---|---|
| Uploaded | Save the file and assign its content version | Upload received |
| Pending review | Submit the image and record the task ID | Awaiting review |
| Assessment complete | Read task status, supported categories, and scores | Review continues until a product decision is made |
| Approved | Apply the product rules and make the image visible | Published |
| Human review | Hold the image and assign a reviewer | Awaiting a decision |
| Rejected or unable to process | Explain the rule or technical issue and offer an appropriate next step | A reason to edit, retry, or appeal |
Poyo supplies the category assessment and task result that connect these stages. Use the task ID or completion callback to update the matching upload in your application, then apply your rules to publish it, hold it for a reviewer, or request a change. Your existing publishing system and review tools carry out those actions.
Keep user-facing messages specific. “Your photo is waiting for review” is useful while processing is incomplete. “We couldn't process this upload; please try again” describes a technical problem. Neither should be replaced by “Your image violates our rules” unless a content decision actually supports that message.
Submit an image through Poyo
You can test an image in the Omni Moderation Playground without writing code or manually creating an API key. Sign in, clear the text if you want an image-only check, add one image, and select Run. Use the new task result rather than the recorded example initially displayed.
For an integration, submit from your server with a Poyo API key:
curl -X POST https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer YOUR_POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "omni-moderation-latest",
"input": {
"image_urls": ["https://your-image-host.example/upload.jpg"]
}
}'
Replace the example domain with an accessible HTTPS URL pointing to the image file. For a no-code trial with a local file, upload the image through the Playground; for API requests, provide its hosted URL in input.image_urls.
To include a caption, add "prompt": "The caption being reviewed" inside input. For multiple images in a post, submit separate tasks and record which result belongs to each image. Approving one image should not automatically approve the rest.
The submission returns a task_id. Retrieve the status using:
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer YOUR_POYO_API_KEY"
A task starts with not_started, runs asynchronously, and finishes with finished or failed. For completed tasks, read the results under data.output.results.
You can also provide a top-level callback_url in the submission. The callback body is the status data object without the outer wrapper, so the results are under output.results. Verify callbacks using the Poyo webhook guidance, and make your handler tolerate repeated delivery.
Turn the assessment into a decision
Begin with a plain-language rule for each category that matters to the surface. Then evaluate whether the model signal helps apply that rule.
An image that clearly violates your policy may be rejected after the appropriate checks. An acceptable image can be published once all required checks finish. Ambiguous cases should remain in review rather than being forced into a decision because a timer expired.
A high score is a reason to examine the corresponding category. It is not a percentage guarantee of a policy violation. The interpretation may depend on whether the image is an artwork, medical illustration, news photograph, or casual user photo.
Use your own labeled examples to choose routing thresholds. Check acceptable images held unnecessarily, as well as prohibited images missed by the workflow. If you change a threshold, compare the results with your previous policy before expanding automatic actions.
Record enough information to explain decisions: content version, task ID, category signals, applied rule, reviewer outcome if any, and decision time. Set retention and access controls for this record rather than storing every raw image indefinitely.
Handle failures, edits, and appeals
An image cannot be retrieved. Check that the URL points to the image itself, remains valid, and is reachable without a user session. Keep the upload pending while you resolve the technical issue.
A request is still running when the page stops waiting. Preserve the task ID and check its status. Submitting a duplicate immediately may leave two tasks reviewing the same version. Use bounded retries and a defined fallback when processing remains unavailable.
A user replaces the file or changes its caption. Treat the change as a new reviewable version. An old approval should not authorize new content. Recheck the relevant inputs, and ensure late callbacks for the old version cannot publish the new one.
A user disputes the decision. Provide an appeal route with enough context for a person to assess the content and applied rule. A successful appeal should update the publishing state and leave an auditable correction.
A post contains several images. Make the publishing rule explicit: for example, wait until every required image task completes, or allow the user to remove the image that needs review. Do not interpret one successful result as a review of the entire post.
Frequently asked questions
What is image moderation?
Image moderation is the process of reviewing pictures against a platform's content rules. It can combine automated checks with human judgment to decide whether an upload should be published, held for review, or rejected.
Is image moderation free on Poyo?
Poyo's Omni Moderation image calls cost zero credits. You can test a supported image assessment in the Playground and then use it in your application without a per-call moderation charge. Plan image storage, delivery, and any human review separately; the free access guide explains the distinction.
Can I review an image and its caption together?
Yes. Add both input.image_urls with one HTTPS image URL and input.prompt with the caption to the same request. In the Playground, provide the image and text together. Read category_applied_input_types to see which signals apply to the supplied text, the image, or both.
Which image risks can I check?
Omni Moderation supports six image categories covering sexual content, violence, graphic violence, self-harm, self-harm intent, and self-harm instructions. Poyo returns category flags and scores you can use to route uploads according to your rules. The capability section above explains the input coverage and additional processing for other requirements.
How do I receive the completed image result?
Save the returned Poyo task ID and query its status, or provide a callback_url for a completion notification. Read data.output.results in status responses or output.results in callbacks. Match the result to the uploaded image version, then let your application publish it or send it to your existing review tool.
How can I test image moderation without code?
Sign in to the Poyo Playground, add one image, optionally enter its caption, and select Run. For an image-only test, clear the text field. Inspect the newly completed task and try representative permitted examples before configuring automatic publishing rules.
Try one image in the Poyo Playground, then connect the result to a publishing rule your team can explain. The AI moderation introduction explains the response fields, and the UGC moderation guide covers the wider team process.