> ## 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.
# Face Detection Result
> Query image, video, or GIF face detection task status and retrieve the detect_id and faces list required for multi-face swap.
## Overview
After creating a face detection task, call this endpoint to query detection status. When the task succeeds,
`data.result.id` is the `detect_id` used by multi-face swap requests, and `data.result.faces` contains each detected
face ID and face image URL.
The `detect_id` is valid for one hour. The media URL passed to the swap request must be the same URL used during detection.
## API Endpoint
```
GET https://api.crun.ai/api/v1/client/job/detect-face-result
```
## Request Parameters
The `detect_task_id` returned when creating a face detection task.
## Status Values
| Status | Description |
| ------------ | ----------- |
| `starting` | Starting |
| `processing` | Processing |
| `succeeded` | Succeeded |
| `failed` | Failed |
## Succeeded Response Example
```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
}
}
```
## Processing Response Example
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"detect_task_id": "dit9ka6i5qoc519iv0",
"result": null,
"status": "processing",
"error": null
}
}
```
## Failed Response Example
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"detect_task_id": "dit9ka6i5qoc519iv0",
"result": null,
"status": "failed",
"error": {
"code": "FaceSwap.Detect.Failed",
"message": "[任务NDm40D2DQp6] 未检测到人脸，源文件未检测到人脸"
}
}
}
```
## Related Resources
Create an image face detection task
Create a video or GIF face detection task
## OpenAPI
````yaml ai-tools/face-swap/detect-face-result.json get /api/v1/client/job/detect-face-result
openapi: 3.0.0
info:
title: Crun Face Detect Result API
description: crun.ai Face Detect Result 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-result:
get:
summary: Get face detection result
operationId: detect-face-result
parameters:
- name: detect_task_id
in: query
required: true
schema:
type: string
description: The `detect_task_id` returned when creating a face detection task.
example: dit60yt8reqplt1c16
responses:
'200':
description: Request successful
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: >-
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
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: Face detection task status.
error:
type: object
nullable: true
properties:
code:
type: string
example: FaceSwap.Detect.Failed
message:
type: string
example: '[TaskNDm40D2DQp6] No face detected in the source file'
required:
- detect_task_id
- result
- status
- error
DetectOutput:
type: object
properties:
id:
type: string
description: >-
Detection result ID. Pass this value as `detect_id` for multi-face
swap.
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: The face ID in the detection result.
example: 0
link:
type: string
format: uri
description: Detected face image URL.
example: https://example.com/detected-face-0.jpg
required:
- id
- link
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
````