Checking Images

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.

To moderate images standalone (without text context), use the Artifact Check endpoint instead.

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 directly in the request. White Circle analyzes the image together with the text:

{
  "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:

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

mime_type is optional — the image format is automatically detected from the content bytes.

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:

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

By external ID:

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

If multiple artifacts share the same external_artifact_id, White Circle uses the most recently created one in the same deployment.

Content and ID Combinations

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

Combination	Behavior
`content` only	Creates a new inline artifact and checks it. Must be `kind: "image"`.
`content` + `external_artifact_id`	Creates a new inline artifact with your custom ID. The artifact is checked as part of this session.
`internal_artifact_id` only	References an existing artifact by its system-generated ID.
`external_artifact_id` only	References an existing artifact by your custom ID.
`internal_artifact_id` + `external_artifact_id`	Looks up by `internal_artifact_id` first, falls back to `external_artifact_id` if not found.
`content` + `internal_artifact_id`	Not allowed — returns 400 error. Use `content` for inline or `internal_artifact_id` for reference.

When you provide both content and external_artifact_id (without internal_artifact_id), a new artifact is always created — even if an artifact with the same external_artifact_id already exists. The new artifact will be returned on future lookups by that external ID.

Only kind: "image" is supported for inline artifacts in session checks. For video or website content, use the Artifact Check endpoint and reference the result by ID.

Combining Text and Images

A single message can contain text and multiple images:

{
  "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:

{
  "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"
    }
  ]
}

Only the last message in the messages array is evaluated for policy violations. Images in earlier messages serve only as context.

Supported Formats

Format	MIME type
JPEG	`image/jpeg`
PNG	`image/png`
WebP	`image/webp`
GIF	`image/gif`

Maximum file size: 20 MB.

Response

Session checks now return an envelope with a session-level result and an artifact list:

{
  "session": {
    "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"]
      }
    }
  },
  "artifacts": [
    {
      "flagged": true,
      "kind": "image",
      "status": "completed",
      "internal_artifact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

For the full session envelope shape, see Check Content. Each object in artifacts[] uses the same response shape as Get Artifact Results. When both text and image contribute to the session-level violation, session.policies.*.flagged_source includes both:

{
  "session": {
    "flagged": true,
    "internal_session_id": "a3e733b5-d6c4-473d-82d4-669c1e757256",
    "policies": {
      "a4a91875-1e54-42d7-b9b0-a75dfebeb057": {
        "name": "Mixed Content Violation",
        "flagged": true,
        "flagged_source": ["text", "image"]
      }
    }
  },
  "artifacts": [
    {
      "flagged": true,
      "kind": "image",
      "status": "completed",
      "internal_artifact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

Artifact Entry in `artifacts[]`

When you send an inline artifact content part, the session response includes the artifact details inside artifacts[]. Each artifact object follows this structure:

{
  "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": "2026-04-15T10: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": "2026-04-15T10:30:00Z",
  "note": null
}

Field	Type	Description
`flagged`	boolean \| null	`true` if any policy was violated. `null` while processing or on failure.
`policies`	object	Map of policy IDs to their violation statuses
`kind`	string	Content type (e.g., `"image"`)
`status`	string	`"completed"` for images. Other statuses: `"processing"`, `"failed"`.
`updated_at`	string	ISO 8601 last update timestamp
`internal_artifact_id`	string	System-generated UUID for this artifact
`external_artifact_id`	string	Your custom artifact ID (if provided)
`external_session_id`	string	External ID of the parent session (if provided)
`internal_session_id`	string	System-generated UUID of the parent session
`created_at`	string	ISO 8601 creation timestamp
`note`	string	Informational 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.

{
  "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:

{
  "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:" }
      ]
    }
  ]
}

First Steps

Use Cases

Integrations

Sessions

Artifacts

Policy

Metric

User

Using Artifacts in Session Checks

Inline Image

Reference a Pre-checked Artifact

Content and ID Combinations

Combining Text and Images

Supported Formats

Response

Artifact Entry in `artifacts[]`

Best Practices

​Using Artifacts in Session Checks

​Inline Image

​Reference a Pre-checked Artifact

​Content and ID Combinations

​Combining Text and Images

​Supported Formats

​Response

​Artifact Entry in artifacts[]

​Best Practices

Using Artifacts in Session Checks

Inline Image

Reference a Pre-checked Artifact

Content and ID Combinations

Combining Text and Images

Supported Formats

Response

Artifact Entry in `artifacts[]`

Best Practices