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

# Image Face Swap (Multi)

> Replace selected faces in an image by mapping detection face IDs to target face images.

## Overview

Image multi-face swap replaces one or more faces by face ID. Create a detection task first, query the detection result to get `detect_id` and the `faces` list, then use the `faces` array in the swap request to map each face to its target image.

<Warning>
  The `detect_id` is valid for one hour. The media URL passed to the swap request must be the same image URL used during detection.
</Warning>

## Process Flow

<Steps>
  <Step title="Create a detection task">
    Call the [face detection endpoint](/ai-tools/face-swap/detect-face-image) with the image URL you want to swap.
  </Step>

  <Step title="Query detection result">
    Call the [face detection result endpoint](/ai-tools/face-swap/detect-face-result) to get `result.id` as `detect_id`, and read face IDs and face images from `result.faces`.
  </Step>

  <Step title="Submit multi-face swap">
    Set the target image URL for each `face_id` in the `faces` array.
  </Step>
</Steps>

## Request Example

```json theme={null}
{
  "model": "image-face-swap-multi",
  "callback_url": "https://your-domain.com/api/callback",
  "input": {
    "detect_id": "m1oZzqYp9dN",
    "image_url": "https://example.com/group-photo.png",
    "faces": [
      {
        "face_id": 0,
        "target": "https://example.com/new-face-0.jpg"
      },
      {
        "face_id": 1,
        "target": "https://example.com/detected-face-1.jpg"
      }
    ]
  }
}
```

If you do not want to replace a face, keep that `face_id`'s `target` as the detected face image URL returned by the previous step.

## Parameters

<ParamField body="detect_id" type="string" required>
  Detection result ID returned by `data.result.id` from the face detection result endpoint.
</ParamField>

<ParamField body="image_url" type="string" required>
  URL of the target image. It must match the media URL used for detection.
</ParamField>

<ParamField body="faces" type="array" required>
  An array describing which faces should be replaced. Each item contains `face_id` and `target`.
</ParamField>

<ParamField body="faces[].face_id" type="integer" required>
  The ID of the face from detection results.
</ParamField>

<ParamField body="faces[].target" type="string" required>
  The target face image URL. Use a new face image URL to replace the face, or keep the detected face image URL if you do not want to replace it.
</ParamField>

## Query Task Status

After submitting a task, use the unified query endpoint to check progress and retrieve results:

<Card title="Get Task Info" icon="magnifying-glass" href="/models/common/get-task-info">
  Learn how to query task status and retrieve generation results
</Card>

<Tip>
  For production use, we recommend using `callback_url` to receive automatic notifications when the task completes, rather than polling the status endpoint.
</Tip>

## Related Resources

<CardGroup cols={2}>
  <Card title="Face Detection Result" icon="search" href="/ai-tools/face-swap/detect-face-result">
    Query detection status and retrieve `detect_id` with detected faces
  </Card>

  <Card title="Common API" icon="gear" href="/common-api/get-account-credits">
    Check credits and account usage
  </Card>
</CardGroup>


## OpenAPI

````yaml ai-tools/face-swap/image-face-swap-multi.json post /api/v1/client/job/CreateTask
openapi: 3.0.0
info:
  title: Crun Image Multi-Face Swap API
  description: crun.ai Image Multi-Face Swap 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/CreateTask:
    post:
      summary: Image multi-face swap
      operationId: image-face-swap-multi
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                  enum:
                    - image-face-swap-multi
                  description: >-
                    The model name to use for this endpoint. Must be
                    `image-face-swap-multi`.
                callback_url:
                  type: string
                  format: uri
                  description: >-
                    Optional. Callback URL for receiving task completion
                    notifications.
                  example: https://your-domain.com/api/callback
                input:
                  $ref: '#/components/schemas/ImageFaceSwapMultiInput'
            example:
              model: image-face-swap-multi
              callback_url: https://your-domain.com/api/callback
              input:
                detect_id: m1oZzqYp9dN
                image_url: https://example.com/group-photo.png
                faces:
                  - face_id: 0
                    target: https://example.com/new-face-0.jpg
                  - face_id: 1
                    target: https://example.com/detected-face-1.jpg
                disable_safety_checker: false
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          task_id:
                            type: string
                            description: >-
                              Task ID, can be used with Get Task Details
                              endpoint to query task status
                            example: task_12345678
              example:
                code: 200
                message: success
                data:
                  task_id: task_12345678
        '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:
    ImageFaceSwapMultiInput:
      type: object
      description: Input parameters for multi-face swap.
      properties:
        detect_id:
          type: string
          description: >-
            Detection result ID returned as `result.id` by the detect result
            endpoint.
          example: m1oZzqYp9dN
        image_url:
          type: string
          format: uri
          description: URL of the target image. It must match the image used for detection.
          example: https://example.com/group-photo.png
        faces:
          type: array
          description: '`face_map` array describing which faces should be replaced.'
          items:
            $ref: '#/components/schemas/FaceMapItem'
          minItems: 1
        disable_safety_checker:
          type: boolean
          nullable: true
          description: Disable the safety filter.
          default: null
          example: false
      required:
        - detect_id
        - image_url
        - faces
    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
    FaceMapItem:
      type: object
      description: Mapping between a detected face ID and the target face image URL.
      properties:
        face_id:
          type: integer
          description: The ID of the face from detection results.
          example: 0
        target:
          type: string
          format: uri
          description: >-
            Target face image URL. Use a new face image URL to replace the face,
            or keep the detected face image URL when you do not want to replace
            it.
          example: https://example.com/new-face-1.jpg
      required:
        - face_id
        - target
  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

````