> ## 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_task_id`，你需要再调用[人脸检测结果接口](/zh/ai-tools/face-swap/detect-face-result)查询状态，并在成功后获取 `detect_id` 与人脸列表。

## 接口地址

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

## 请求参数

<ParamField body="image_url" type="string" required>
  需要检测人脸的图片 URL。
</ParamField>

## 请求示例

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

## 响应示例

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

## 下一步

<Card title="查询人脸检测结果" icon="search" href="/zh/ai-tools/face-swap/detect-face-result">
  查询检测任务状态，获取多人换脸需要的 detect\_id 和 faces 列表
</Card>

## 相关资源

<CardGroup cols={2}>
  <Card title="图片多人换脸" icon="image" href="/zh/ai-tools/face-swap/image-face-swap-multi">
    使用 `detect_id` 和 `faces` 替换图片中的指定人脸
  </Card>

  <Card title="人脸检测结果" icon="search" href="/zh/ai-tools/face-swap/detect-face-result">
    查询检测状态并获取人脸列表
  </Card>
</CardGroup>


## OpenAPI

````yaml zh/ai-tools/face-swap/detect-face-image.json post /api/v1/client/job/detect-face-image
openapi: 3.0.0
info:
  title: Crun 图片人脸检测 API
  description: crun.ai 图片人脸检测 API 文档
  version: 1.0.0
  contact:
    name: 技术支持
    email: support@crun.ai
servers:
  - url: https://api.crun.ai
    description: API 服务器
security:
  - ApiKeyAuth: []
paths:
  /api/v1/client/job/detect-face-image:
    post:
      summary: 创建图片人脸检测任务
      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。
                  example: https://example.com/source.png
            example:
              image_url: https://example.com/source.png
      responses:
        '200':
          description: 请求成功
          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: 验证错误
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      errors:
                        type: array
                        description: 详细的参数验证错误信息
                        items:
                          type: string
                        example:
                          - 具体字段错误信息
              example:
                code: 422
                message: Missing Params or Type Error
                errors:
                  - 具体字段错误信息
        '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: |-
            响应状态码

            - **200**：成功 - 请求已成功处理
            - **401**：未授权 - 认证凭据缺失或无效
            - **402**：余额不足 - 账户积分不足，无法执行操作
            - **404**：未找到 - 请求的资源或接口不存在
            - **422**：验证错误 - 请求参数未通过校验
            - **429**：请求过多 - 已超过该资源的请求限制
            - **455**：服务不可用 - 系统正在维护
            - **500**：服务器错误 - 处理请求时发生意外错误
            - **501**：生成失败 - 内容生成任务失败
            - **505**：功能已禁用 - 请求的功能当前不可用
        message:
          type: string
          description: 响应消息，失败时为错误描述
          example: success
    DetectTaskResponse:
      type: object
      properties:
        detect_task_id:
          type: string
          description: 人脸检测任务 ID，用于查询检测结果。
          example: dit60yt8reqplt1c16
      required:
        - detect_task_id
  responses:
    Error:
      description: 服务器错误
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |-
        所有 API 都需要通过 API Key 认证。

        获取 API Key：
        1. 访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取你的 API Key

        使用方式：
        添加到请求头：

        x-api-key: YOUR_API_KEY

        注意：
        - 请妥善保管你的 API Key，不要分享给他人
        - 如果怀疑 API Key 已泄露，请立即在管理页面重置

````