Content

Send content to Stream and get a keep, flag, or remove decision. There are two endpoints. Both use the same policies and rules.

Which should I use?

Use Custom Check when your own model already classified the content and you want that result on the dashboard.

Examples below use the server-side SDKs. See the setup guides for Node, Python, Go, Java, PHP, Ruby, or .NET.

Check

Submit text, image URLs, and/or video URLs. Get back one recommended_action (keep, flag, or remove) and a review-queue item you can show on a custom dashboard.

1. Create a policy with engines and actions
2. Call check with your entity ids and config_key
3. Apply recommended_action in your product
4. Review flagged items in the dashboard or via the review queue API

API Usage

response = client.moderation().check(
    entity_type="entity_type",
    entity_id="entity_id",
    entity_creator_id="entity_creator_id",
    moderation_payload=ModerationPayload(
        texts=["this is bullshit", "f*ck you as***le"],
        images=["example.com/test.jpg"],
    ),
    config_key="config_key",
    options={"force_sync": True},
)

Request Params

Response

Analyze

Submit named text fields and get a keep / flag / remove decision per label. Use it when you need a verdict per field instead of one action for the whole entity.

Server-side only. Call analyze the same way as check for named texts. At least one text field or image is required.

Raw image bytes are not in the SDK. Send them with an HTTP multipart/form-data request: one JSON payload part plus image:<label> file parts. That is the only way to attach bytes today.

Modes

Stateful vs stateless. Send entity_type, entity_id, and entity_creator_id together to persist a review-queue row (when content is flagged) and evaluate rules. Omit all three for a stateless call: verdicts only, no queue, no webhooks. config_key is required when stateless. Partial entity fields return 400.

entity_type is yours (listing, external:call). Types that start with stream: are reserved. You may add a subtype for routing (external:call:keyframe); webhooks echo the canonical type (external:call).

Sync vs async. Default is sync: verdicts in the HTTP body. Set async_response: true (stateful only) to get status: "pending" and receive moderation.text_analysis.complete / moderation.image_analysis.complete webhooks instead. Do not send async_response: true without entity fields.

Calling Analyze

response = client.moderation().analyze(
    entity_type="listing",
    entity_id="listing_42",
    entity_creator_id="user_42",
    config_key="catalog-v1",
    content_ids={"caption": "cap_42"},
    texts={"caption": "Vintage watch, mint condition"},
)

Image bytes (HTTP only)

client.moderation.analyze sends the JSON fields above. It cannot attach files. To send raw image bytes, POST multipart/form-data yourself (max 10 images, 250 KB each by default, 20 MB for the whole request):

curl -X POST "https://chat.stream-io-api.com/api/v2/moderation/analyze?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -F 'payload={"entity_type":"listing","entity_id":"listing_42","entity_creator_id":"user_42","config_key":"catalog-v1","texts":{"caption":"Vintage watch, mint condition"},"content_ids":{"caption":"cap_42","main_photo":"img_42_main"}};type=application/json' \
  -F "image:main_photo=@frame.jpg;type=image/jpeg"

Analyze request

Images: HTTP only. Each file part is named image:<label>. Max 10 images, 250 KB each by default, 20 MB for the whole request. The SDK analyze method does not accept file parts.

Analyze response

Successful calls return 201.

Each text or image field:

{
  "status": "complete",
  "texts": {
    "caption": {
      "id": "cap_42",
      "action": "flag",
      "classifications": [{ "name": "INSULT", "severity": "high" }],
      "severity": "high",
      "language": "en"
    }
  },
  "images": {
    "main_photo": {
      "id": "img_42_main",
      "action": "keep"
    }
  }
}

If some fields fail, status is partial (still 201). Retry only the labels with error. If nothing could be screened, the API returns 503 with a standard error envelope, not this body. Bad input is 400. A missing policy is 422.

Async pending body:

{ "status": "pending", "duration": "112.84ms" }

Wait for Analyze webhook events. A provider error stays on *.complete as field error. moderation.analysis.failed means Stream could not finish the listed content_ids after the pending ack. Treat those ids as unscreened.

Custom Check

Custom Check enables you to submit your own AI moderation results of a chat message/custom uploaded content for review by moderators on the Dashboard.

Add Custom Flags to a Chat Message

Custom Flags can be added to a Chat message. This enables you to submit your own AI moderation results of a chat message for review by moderators on the Dashboard.

client.moderation().custom_check(
    entity_type="stream:chat:v1:message",
    entity_id=message_id,
    entity_creator_id="user_id",
    flags=[
        CustomCheckFlag(type="custom_check_image", reason="Image was NSFW", labels=["NSFW"]),
        CustomCheckFlag(type="custom_check_text", reason="Text was harmful", labels=["harmful"]),
        CustomCheckFlag(type="custom_check_video", reason="Video contains copyright material", labels=["copyright-violation"]),
    ],
)

Add Custom Check Flags to the Custom Content

The Custom Check endpoint enables you to submit your own AI moderation results for the custom content for review by moderators on the Dashboard.

client.moderation().custom_check(
    entity_type="entity_type",
    entity_id="entity_id",
    entity_creator_id="entity_creator_id",
    moderation_payload=ModerationPayload(texts=["offensive"]),
    flags=[
        CustomCheckFlag(
            type="custom_check_text",
            reason="Text was offensive",
            custom={"explaination": "custom is a nullable field allowing you to attach a custom object to the flag for your specific use cases or requirements"},
        ),
    ],
)

Request Params

Response

Related APIs

• Policies to configure engines and actions
• Rules for aggregation and automated actions
• Review Queue to inspect flagged items
• Flag, Mute & Ban
• Webhooks
• Appeals
• Logs & Analytics