# 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.

> [!TIP]
> To moderate images **standalone** (without text context), use the [Artifact Check](https://whitecircle.com/docs/2026-04-15/artifact/check-artifact.md) 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](https://whitecircle.com/docs/2026-04-15/artifact/check-artifact.md).

### Inline Image

Send the image directly 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..."
  }
}
```

> [!NOTE]
> `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](https://whitecircle.com/docs/2026-04-15/artifact/check-artifact.md), 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"
}
```

> [!NOTE]
> 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. |

> [!WARNING]
> 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.

> [!NOTE]
> Only `kind: "image"` is supported for inline artifacts in session checks. For video or website content, use the [Artifact Check](https://whitecircle.com/docs/2026-04-15/artifact/check-artifact.md) endpoint and reference the result by ID.

## 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"
    }
  ]
}
```

> [!NOTE]
> 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:

```json
{
  "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](https://whitecircle.com/docs/2026-04-15/session/check-session.md). Each object in `artifacts[]` uses the same response shape as [Get Artifact Results](https://whitecircle.com/docs/2026-04-15/artifact/get-artifact.md).

When both text and image contribute to the session-level violation, `session.policies.*.flagged_source` includes both:

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

```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": "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.

```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](https://whitecircle.com/docs/2026-04-15/artifact/check-artifact.md), 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:" }
      ]
    }
  ]
}
```
