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

# Detect Face (Image)

> Create a face detection task for image multi-face swap.

## Overview

Before multi-face swap, call this endpoint to create an image face detection task. The endpoint returns `detect_task_id`; call the [face detection result endpoint](/ai-tools/face-swap/detect-face-result) to query status and retrieve `detect_id` with the detected face list after success.

## API Endpoint

```
POST https://api.crun.ai/api/v1/client/job/detect-face-image
```

## Request Parameters

<ParamField body="image_url" type="string" required>
  URL of the image to detect faces from.
</ParamField>

## Request Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.crun.ai/api/v1/client/job/detect-face-image" \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_API_KEY" \
    -d "{\"image_url\":\"https://example.com/source.png\"}"
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.crun.ai/api/v1/client/job/detect-face-image"
  headers = {
      "Content-Type": "application/json",
      "X-API-KEY": "YOUR_API_KEY",
  }
  payload = {
      "image_url": "https://example.com/source.png",
  }

  response = requests.post(url, json=payload, headers=headers, timeout=30)
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const url = "https://api.crun.ai/api/v1/client/job/detect-face-image";
  const payload = {
    image_url: "https://example.com/source.png",
  };

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "YOUR_API_KEY",
    },
    body: JSON.stringify(payload),
  });

  console.log(await response.json());
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "detect_task_id": "dit60yt8reqplt1c16"
  }
}
```

## Next Step

<Card title="Query Face Detection Result" icon="search" href="/ai-tools/face-swap/detect-face-result">
  Query detection status and get the detect\_id and faces list required for multi-face swap
</Card>

## Related Resources

<CardGroup cols={2}>
  <Card title="Image Multi-Face Swap" icon="image" href="/ai-tools/face-swap/image-face-swap-multi">
    Replace selected faces in an image using `detect_id` and `faces`
  </Card>

  <Card title="Face Detection Result" icon="search" href="/ai-tools/face-swap/detect-face-result">
    Query detection status and retrieve the face list
  </Card>
</CardGroup>


## OpenAPI

````yaml ai-tools/face-swap/detect-face-image.json post /api/v1/client/job/detect-face-image
openapi: 3.0.0
info:
  title: Crun Image Face Detect API
  description: crun.ai Image Face Detect API Documentation
  version: 1.0.0
  contact:
    name: Technical Support
    email: support@crun.ai
servers:
  - url: https://api.crun.ai
    description: API Server
security:
  - ApiKeyAuth: []
paths:
  /api/v1/client/job/detect-face-image:
    post:
      summary: Create an image face detection task
      operationId: detect-face-image
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
              properties:
                image_url:
                  type: string
                  format: uri
                  description: URL of the image to detect faces from.
                  example: https://example.com/source.png
            example:
              image_url: https://example.com/source.png
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/DetectTaskResponse'
              example:
                code: 200
                message: success
                data:
                  detect_task_id: dit60yt8reqplt1c16
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      errors:
                        type: array
                        description: Detailed validation error messages
                        items:
                          type: string
                        example:
                          - specific error field message
              example:
                code: 422
                message: Missing Params or Type Error
                errors:
                  - specific error field message
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          enum:
            - 200
            - 401
            - 402
            - 404
            - 422
            - 429
            - 455
            - 500
            - 501
            - 505
          description: >-
            Response status code


            - **200**: Success - Request has been processed successfully

            - **401**: Unauthorized - Authentication credentials are missing or
            invalid

            - **402**: Insufficient Credits - Account does not have enough
            credits to perform the operation

            - **404**: Not Found - The requested resource or endpoint does not
            exist

            - **422**: Validation Error - The request parameters failed
            validation checks

            - **429**: Rate Limited - Request limit has been exceeded for this
            resource

            - **455**: Service Unavailable - System is currently undergoing
            maintenance

            - **500**: Server Error - An unexpected error occurred while
            processing the request

            - **501**: Generation Failed - Content generation task failed

            - **505**: Feature Disabled - The requested feature is currently
            disabled
        message:
          type: string
          description: Response message, error description when failed
          example: success
    DetectTaskResponse:
      type: object
      properties:
        detect_task_id:
          type: string
          description: Face detection task ID used to query detection results.
          example: dit60yt8reqplt1c16
      required:
        - detect_task_id
  responses:
    Error:
      description: Server Error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        All APIs require authentication via API Key.


        Get API Key:

        1. Visit [API Key Management Page](https://crun.ai/user-api-key) to get
        your API Key


        Usage:

        Add to request header:


        x-api-key: YOUR_API_KEY


        Note:

        - Keep your API Key secure and do not share it with others

        - If you suspect your API Key has been compromised, reset it immediately
        in the management page

````