> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitecircle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/2025-12-01/artifact/check-artifact) endpoint instead.</Tip>

<Warning>`image_url` and `input_image` content parts are not supported in session checks. Use `artifact` content parts for images in sessions.</Warning>

## 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](/2025-12-01/artifact/check-artifact).

### Inline Image

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

```json highlight={7-14} theme={null}
{
  "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 theme={null}
{
  "type": "artifact",
  "content": {
    "kind": "image",
    "data": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}
```

<Info>`mime_type` is optional — the image format is automatically detected from the content bytes.</Info>

### Reference a Pre-checked Artifact

If you've already checked an image via [Artifact Check](/2025-12-01/artifact/check-artifact), 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 theme={null}
{
  "type": "artifact",
  "internal_artifact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

By external ID:

```json theme={null}
{
  "type": "artifact",
  "external_artifact_id": "my-upload-42"
}
```

<Info>If multiple artifacts share the same `external_artifact_id`, White Circle uses the most recently created one in the same deployment.</Info>

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

<Info>Only `kind: "image"` is supported for inline artifacts in session checks. For video or website content, use the [Artifact Check](/2025-12-01/artifact/check-artifact) endpoint and reference the result by ID.</Info>

## Combining Text and Images

A single message can contain text and multiple images:

```json theme={null}
{
  "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 theme={null}
{
  "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"
    }
  ]
}
```

<Info>
  Only the **last message** in the `messages` array is evaluated for policy violations. Images in earlier messages serve only as context.
</Info>

## Supported Formats

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

Maximum file size: 20 MB.

## Response

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

```json theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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
}
```

| 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

<AccordionGroup>
  <Accordion title="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 theme={null}
    {
      "content": [
        {
          "type": "artifact",
          "content": {
            "kind": "image",
            "url": "https://example.com/diagram.png"
          }
        },
        { "type": "text", "text": "Check out this educational diagram" }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Pre-check then reference for efficiency">
    For workflows where the same image appears in multiple sessions, check it once via [Artifact Check](/2025-12-01/artifact/check-artifact), 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.
  </Accordion>

  <Accordion title="Moderate AI-generated images">
    If your application generates images, run them through White Circle before displaying them to users:

    ```json theme={null}
    {
      "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:" }
          ]
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>