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

# 人脸检测结果

> 查询图片、视频或 GIF 人脸检测任务状态，并获取多人换脸需要的 detect_id 与 faces 列表。

## 概述

创建人脸检测任务后，调用此接口查询检测状态。任务成功后，`data.result.id` 即为多人换脸请求中的 `detect_id`，
`data.result.faces` 包含每张检测到的人脸 ID 和人脸图片 URL。

<Warning>
  `detect_id` 有效期为 1 小时。换脸时传入的资源地址要和检测时相同。
</Warning>

## 接口地址

```
GET https://api.crun.ai/api/v1/client/job/detect-face-result
```

## 请求参数

<ParamField query="detect_task_id" type="string" required>
  创建检测任务时返回的 `detect_task_id`。
</ParamField>

## 状态枚举

| 状态           | 说明  |
| ------------ | --- |
| `starting`   | 启动中 |
| `processing` | 处理中 |
| `succeeded`  | 成功  |
| `failed`     | 失败  |

## 成功响应示例

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "detect_task_id": "dit60yt8reqplt1c16",
    "result": {
      "id": "m1oZzqYp9dN",
      "status": "succeed",
      "type": "face_detect",
      "hair_id": null,
      "faces": [
        {
          "id": 0,
          "link": "https://example.com/detected-face-0.jpg"
        },
        {
          "id": 1,
          "link": "https://example.com/detected-face-1.jpg"
        }
      ],
      "started_at": "2026-05-27 12:14:03",
      "finished_at": "2026-05-27 12:14:04",
      "error": null
    },
    "status": "succeeded",
    "error": null
  }
}
```

## 处理中响应示例

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "detect_task_id": "dit9ka6i5qoc519iv0",
    "result": null,
    "status": "processing",
    "error": null
  }
}
```

## 失败响应示例

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "detect_task_id": "dit9ka6i5qoc519iv0",
    "result": null,
    "status": "failed",
    "error": {
      "code": "FaceSwap.Detect.Failed",
      "message": "[任务NDm40D2DQp6] 未检测到人脸，源文件未检测到人脸"
    }
  }
}
```

## 相关资源

<CardGroup cols={2}>
  <Card title="检测人脸（图片）" icon="image" href="/zh/ai-tools/face-swap/detect-face-image">
    创建图片人脸检测任务
  </Card>

  <Card title="检测人脸（视频和 GIF）" icon="video" href="/zh/ai-tools/face-swap/detect-face-video">
    创建视频或 GIF 人脸检测任务
  </Card>
</CardGroup>


## OpenAPI

````yaml zh/ai-tools/face-swap/detect-face-result.json get /api/v1/client/job/detect-face-result
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-result:
    get:
      summary: 获取人脸检测结果
      operationId: detect-face-result
      parameters:
        - name: detect_task_id
          in: query
          required: true
          schema:
            type: string
          description: 创建人脸检测任务时返回的 `detect_task_id`。
          example: dit60yt8reqplt1c16
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/DetectResultResponse'
              example:
                code: 200
                message: success
                data:
                  detect_task_id: dit60yt8reqplt1c16
                  result:
                    id: m1oZzqYp9dN
                    status: succeed
                    type: face_detect
                    hair_id: null
                    faces:
                      - id: 0
                        link: https://example.com/detected-face-0.jpg
                      - id: 1
                        link: https://example.com/detected-face-1.jpg
                    started_at: '2026-05-27 12:14:03'
                    finished_at: '2026-05-27 12:14:04'
                    error: null
                  status: succeeded
                  error: null
        '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
    DetectResultResponse:
      type: object
      properties:
        detect_task_id:
          type: string
          example: dit60yt8reqplt1c16
        result:
          $ref: '#/components/schemas/DetectOutput'
          nullable: true
        status:
          type: string
          enum:
            - starting
            - processing
            - succeeded
            - failed
          description: 检测任务状态。
        error:
          type: object
          nullable: true
          properties:
            code:
              type: string
              example: FaceSwap.Detect.Failed
            message:
              type: string
              example: '[任务NDm40D2DQp6] 未检测到人脸，源文件未检测到人脸'
      required:
        - detect_task_id
        - result
        - status
        - error
    DetectOutput:
      type: object
      properties:
        id:
          type: string
          description: 检测结果 ID。多人换脸时作为 `detect_id` 传入。
          example: m1oZzqYp9dN
        status:
          type: string
          example: succeed
        type:
          type: string
          example: face_detect
        hair_id:
          type: string
          nullable: true
          example: null
        faces:
          type: array
          items:
            $ref: '#/components/schemas/DetectFaceItem'
        started_at:
          type: string
          example: '2026-05-27 12:14:03'
        finished_at:
          type: string
          example: '2026-05-27 12:14:04'
        error:
          type: object
          nullable: true
          example: null
    DetectFaceItem:
      type: object
      properties:
        id:
          type: integer
          description: 检测结果中的人脸 ID。
          example: 0
        link:
          type: string
          format: uri
          description: 检测到的人脸图片 URL。
          example: https://example.com/detected-face-0.jpg
      required:
        - id
        - link
  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 已泄露，请立即在管理页面重置

````