# AI Image Detector Async

> Submit an image URL for AI-generated content detection. Results are delivered asynchronously via webhook.

Submit an image URL for AI-generated content detection. The endpoint is **asynchronous** - it returns `201 Created` immediately, and the detection results are delivered to your webhook URL once processing is complete.

Use this endpoint when you have a publicly reachable image URL and prefer a fire-and-forget submission. For an immediate, synchronous response with the image uploaded directly in the request, use [AI Image Detection](/reference/actions/ai-image-detector/check) instead.

Authentication is required. See [Login](/reference/actions/account/login) for how to obtain a bearer token.

<Note>
  This is a new endpoint and the official Copyleaks SDKs (Python, JavaScript, Java, C#, PHP, Ruby) don't yet expose a wrapper method for the async flow. The code samples below call the HTTP API directly. SDK support is planned - until then, use the raw HTTP pattern.
</Note>

## Path parameters

<ParamField path="scanId" type="string" required>
  A unique scan id provided by you. We recommend using the same id in your database to represent the scan in the Copyleaks database - this helps debug incidents and avoid duplicate scans for the same image. See [criteria for creating a Scan ID](/concepts/management/choosing-scan-id).

  `>= 3 characters` &nbsp; `<= 36 characters`

  Match pattern: ``[a-z0-9] !@$^&-+%=_(){}<>';:/.",~`|``
</ParamField>

## Headers

```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```

## Body parameters

<ParamField body="url" type="string" required>
  Publicly accessible URL of the image file to analyze.

  Example: `"https://example.com/my-image.png"`
</ParamField>

<ParamField body="fileName" type="string" required>
  The name of the image file including its extension.

  **Supported extensions:** `.jpg`, `.jpeg`, `.png`, `.webp`, `.tiff`, `.bmp`, `.heic`, `.heif`

  Example: `"image1.png"`
</ParamField>

<ParamField body="model" type="string" required>
  The AI image detection model to use for analysis.

  - AI Image 1 Ultra: `"ai-image-1-ultra"`

  Example: `"ai-image-1-ultra"`
</ParamField>

<ParamField body="maskType" type="string">
  The type of detection overlay to return alongside the detection result. Use this when you want a pixel-level visualization of which regions of the image were flagged as AI-generated.

  Supported values:
  - `"heatmap"` - gradient overlay highlighting AI-generated regions with intensity proportional to confidence.

  Example: `"heatmap"`
</ParamField>

<ParamField body="objectDetection" type="array">
  Optional. A list of objects to locate and segment within the image. When provided, the result delivered to your webhook additionally includes a `detectedObjects` array - one entry per object found in the image, each with its Run-Length Encoded (RLE) segmentation mask.

  Each entry wraps the object name in an object (`{ "object": "face" }`) so future per-entry fields can be added without a breaking change.

  - Maximum 3 entries.
  - Each entry's `object` value must be a non-empty string of at most 32 characters.

  Example: `[{ "object": "face" }, { "object": "hand" }]`
</ParamField>

<ParamField body="headers" type="array">
  Optional custom headers to include when Copyleaks fetches the image from the provided `url`. Each entry is a two-element array: `["Header-Name", "Header-Value"]`.

  Example: `[["X-Custom-Auth", "my-token"]]`
</ParamField>

<ParamField body="webhooks" type="object" required>
  Webhook configuration for receiving the async results.

  <Expandable title="properties">
    <ParamField body="webhooks.url" type="string" required>
      The URL that Copyleaks will POST the detection results to when processing is complete.

      Example: `"https://your-server.com/webhook/receive-results"`
    </ParamField>
    <ParamField body="webhooks.headers" type="array">
      Optional custom headers to include in the webhook request. Each entry is a two-element array: `["Header-Name", "Header-Value"]`.

      Example: `[["Authorization", "Bearer my-webhook-token"]]`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sandbox" type="boolean" default="false">
  Use sandbox mode to test your integration with the [Copyleaks API](https://copyleaks.com/api) without consuming any credits. Submit images for AI detection and receive mock results simulating the API. Intended for development purposes only.
</ParamField>

<ParamField body="developerPayload" type="string">
  An optional string payload that Copyleaks will include in the webhook response, allowing you to correlate the callback with your internal data.

  Example: `"order-id-12345"`
</ParamField>

<RequestExample>

```bash title="cURL" icon="terminal"
curl --request PUT \
  --url https://api.copyleaks.com/v1/ai-image-detector-async/my-image-scan-1/submit \
  --header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/image1.png",
    "fileName": "image1.png",
    "model": "ai-image-1-ultra",
    "maskType": "heatmap",
    "webhooks": {
      "url": "https://your-server.com/webhook/receive-results"
    }
  }'
```

```python title="Python" icon="python"
import requests

url = 'https://api.copyleaks.com/v1/ai-image-detector-async/my-image-scan-1/submit'
headers = {
    'Authorization': 'Bearer YOUR_LOGIN_TOKEN',
    'Content-Type': 'application/json'
}

payload = {
    'url': 'https://example.com/image1.png',
    'fileName': 'image1.png',
    'model': 'ai-image-1-ultra',
    'maskType': 'heatmap',
    'webhooks': {
        'url': 'https://your-server.com/webhook/receive-results'
    }
}

response = requests.put(url, json=payload, headers=headers)
print(f"Submission status: {response.status_code}")  # 201 Created
```

```javascript title="JavaScript" icon="square-js"
const response = await fetch(
  'https://api.copyleaks.com/v1/ai-image-detector-async/my-image-scan-1/submit',
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_LOGIN_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://example.com/image1.png',
      fileName: 'image1.png',
      model: 'ai-image-1-ultra',
      maskType: 'heatmap',
      webhooks: {
        url: 'https://your-server.com/webhook/receive-results'
      }
    })
  }
);

console.log('Submission status:', response.status); // 201 Created
```

```http title="HTTP" icon="globe"
PUT https://api.copyleaks.com/v1/ai-image-detector-async/my-image-scan-1/submit
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN

{
  "url": "https://example.com/image1.png",
  "fileName": "image1.png",
  "model": "ai-image-1-ultra",
  "maskType": "heatmap",
  "webhooks": {
    "url": "https://your-server.com/webhook/receive-results"
  }
}
```

</RequestExample>

<ResponseExample>

```json 201 Created
{}
```

```json 400 Bad Request
{
  "error": "Invalid request parameters."
}
```

```json 401 Unauthorized
{
  "error": "Authentication or authorization failed."
}
```

```json 402 Payment Required
{
  "error": "Insufficient credits."
}
```

```json 429 Too Many Requests
{
  "error": "Rate limit exceeded."
}
```

```json 500 Internal Server Error
{
  "error": "The server encountered an internal error."
}
```

</ResponseExample>

## Webhook payload

When processing completes, Copyleaks sends a `POST` request to your webhook URL with the detection results. The payload follows the same shape as the synchronous [AI Image Detection](/reference/actions/ai-image-detector/check) response.

When the request included `objectDetection`, the payload additionally contains a `detectedObjects` array - one entry per object found in the image. Objects that were requested but not found are omitted, so look entries up by `object` rather than by position.

<ParamField path="detectedObjects" type="array<object>">
  Present only when `objectDetection` was supplied in the request. One entry per object located in the image.
  <Expandable title="properties">
    <ParamField path="object" type="string">
      The object description from the request that this entry corresponds to.
    </ParamField>
    <ParamField path="mask" type="object">
      The Run-Length Encoded (RLE) segmentation mask for this object.
      <Expandable title="properties">
        <ParamField path="starts" type="array<integer>">
          Starting positions of each segment in the flattened 1D image array.
        </ParamField>
        <ParamField path="lengths" type="array<integer>">
          Lengths of each segment, corresponding to the `starts` array.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>