Sessions

Checking Images

Analyze images alongside text for combined policy violations

White Circle can analyze images alongside text content within a session check. This is useful when the combination of text and image matters for policy evaluation — an image alone might be safe, but paired with certain text it could become a violation.

Using Artifacts in Session Checks

Include images in your session check using the artifact content part type. You can either send an image inline or reference a previously checked artifact. Note that you’re going to be charged for every inline artifact as if it was an independent API call to artifact check.

Inline Image

Send the image as an inline artifact in the request. White Circle analyzes the image together with the text:

JSON

{
  "deployment_id": "your-deployment-id",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "artifact",
          "content": {
            "kind": "image",
            "url": "https://cdn.example.com/uploads/photo.jpg"
          }
        },
        {
          "type": "text",
          "text": "What do you think about this image?"
        }
      ]
    }
  ]
}

Base64 is also supported:

JSON

{
  "type": "artifact",
  "content": {
    "kind": "image",
    "data": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

Reference a Pre-checked Artifact

If you’ve already checked an image via Artifact Check, you can reference it by ID. White Circle uses the existing result and includes the image as context for the text evaluation — without re-checking it. If your entire API request contains only this reference to artifact without any new content at all, you will not be charged.

By internal ID:

JSON

{
  "type": "artifact",
  "internal_artifact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

By external ID:

JSON

{
  "type": "artifact",
  "external_artifact_id": "my-upload-42"
}

Content and ID Combinations

The artifact content part supports different combinations of content, internal_artifact_id, and external_artifact_id:

CombinationBehavior
content onlyCreates a new inline artifact and checks it. Must be kind: "image".
content + external_artifact_idCreates a new inline artifact with your custom ID. The artifact is checked as part of this session.
internal_artifact_id onlyReferences an existing artifact by its system-generated ID.
external_artifact_id onlyReferences an existing artifact by your custom ID.
internal_artifact_id + external_artifact_idLooks up by internal_artifact_id first, falls back to external_artifact_id if not found.
content + internal_artifact_idNot allowed — returns 400 error. Use content for inline or internal_artifact_id for reference.

Combining Text and Images

A single message can contain text and multiple images:

JSON

{
  "deployment_id": "your-deployment-id",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "artifact",
          "content": {
            "kind": "image",
            "url": "https://example.com/photo1.jpg"
          }
        },
        {
          "type": "artifact",
          "content": {
            "kind": "image",
            "url": "https://example.com/photo2.jpg"
          }
        },
        {
          "type": "text",
          "text": "Compare these two photos"
        }
      ]
    }
  ]
}

White Circle evaluates the message once, using all provided images as context for text evaluation.

You can also mix inline and referenced artifacts:

JSON

{
  "content": [
    {
      "type": "artifact",
      "internal_artifact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    {
      "type": "artifact",
      "content": {
        "kind": "image",
        "data": "iVBORw0KGgoAAAANSUhEUgAA..."
      },
      "external_artifact_id": "new-upload-5"
    },
    {
      "type": "text",
      "text": "Combine these two images"
    }
  ]
}

Supported Formats

FormatMIME type
JPEGimage/jpeg
PNGimage/png
WebPimage/webp
GIFimage/gif

Maximum file size: 20 MB.

Response

When an image violates a policy, the flagged_source array includes "image":

JSON

{
  "flagged": true,
  "internal_session_id": "a3e733b5-d6c4-473d-82d4-669c1e757256",
  "policies": {
    "5a920d64-977b-4b38-8679-d5dbb4e2c0c5": {
      "name": "No Explicit Content",
      "flagged": true,
      "flagged_source": ["image"]
    }
  }
}

If both text and image violate policies, both sources are listed:

JSON

{
  "flagged_source": ["text", "image"]
}

Inline Artifact in Response

When you send an inline artifact content part, the session response includes the artifact details. The artifact embedded in the response follows this structure:

JSON

{
  "flagged": true,
  "policies": {
    "4d7543e2-d106-4cac-b0a4-87b27e473813": {
      "name": "No Explicit Content",
      "flagged": true,
      "flagged_source": ["image"]
    },
    "d54a96f1-ccac-4967-9101-46e68eab415e": {
      "name": "No Violence",
      "flagged": false,
      "flagged_source": []
    }
  },
  "kind": "image",
  "status": "completed",
  "updated_at": "2025-12-01T10:30:00Z",
  "internal_artifact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_artifact_id": "my-upload-42",
  "external_session_id": "user-session-123",
  "internal_session_id": "a3e733b5-d6c4-473d-82d4-669c1e757256",
  "created_at": "2025-12-01T10:30:00Z",
  "note": null
}
FieldTypeDescription
flaggedboolean | nulltrue if any policy was violated. null while processing or on failure.
policiesobjectMap of policy IDs to their violation statuses
kindstringContent type (e.g., "image")
statusstring"completed" for images. Other statuses: "processing", "failed".
updated_atstringISO 8601 last update timestamp
internal_artifact_idstringSystem-generated UUID for this artifact
external_artifact_idstringYour custom artifact ID (if provided)
external_session_idstringExternal ID of the parent session (if provided)
internal_session_idstringSystem-generated UUID of the parent session
created_atstringISO 8601 creation timestamp
notestringInformational message (e.g., why an image URL fetch failed)

Best Practices

Include text context with images

When moderating images, include any accompanying text. Context matters — an image might be acceptable in one context but violate policies in another.

JSON

{
  "content": [
    {
      "type": "artifact",
      "content": {
        "kind": "image",
        "url": "https://example.com/diagram.png"
      }
    },
    { "type": "text", "text": "Check out this educational diagram" }
  ]
}
Pre-check then reference for efficiency

For workflows where the same image appears in multiple sessions, check it once via Artifact Check, then reference it by internal_artifact_id in later session checks. White Circle reuses the existing result and includes the image as context for text evaluation.

Moderate AI-generated images

If your application generates images, run them through White Circle before displaying them to users:

JSON

{
  "deployment_id": "your-deployment-id",
  "messages": [
    { "role": "user", "content": "Generate an image of a sunset" },
    {
      "role": "assistant",
      "content": [
        {
          "type": "artifact",
          "content": {
            "kind": "image",
            "url": "https://your-ai/generated/abc.png"
          }
        },
        { "type": "text", "text": "Here's your sunset image:" }
      ]
    }
  ]
}