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

# Detect Faces

> Upload a photo and find every face in it.

Detect faces is the first step of [face search](/concepts/search#face-search). Orbit stores the photo privately and returns a reference to it with every face it finds, left to right.

```bash theme={"dark"}
curl -X POST "https://api.orbitsearch.com/v3/faces/detect" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -F "image=@photo.jpg"
```

## Request

Send the photo as the multipart field `image`. Orbit accepts JPG, PNG, and WebP photos from 50 × 50 pixels up to 25 MB.

## Response

```json theme={"dark"}
{
  "status": "success",
  "payload": {
    "image_url": "face-source:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08.jpg",
    "image_width": 1280,
    "image_height": 960,
    "faces": [
      { "index": 0, "bbox": [212, 140, 388, 356], "det_score": 0.91 },
      { "index": 1, "bbox": [720, 180, 868, 372], "det_score": 0.87 }
    ]
  }
}
```

| Field | Type | Description |
| - | - | - |
| `image_url` | string | The reference to the stored photo. Pass it to [Search the face index](/api/search/faces-index-search) and to `signals.face_source` on [Start a search](/api/search/search). |
| `image_width` | integer or null | The photo's width in pixels. |
| `image_height` | integer or null | The photo's height in pixels. |
| `faces` | array | Every face in the photo, left to right. The array is empty when the photo shows no usable face. |
| `faces[].index` | integer | The face's position in `faces`. |
| `faces[].bbox` | array of 4 integers | The face box `[x0, y0, x1, y1]` in the pixels of the upright photo. |
| `faces[].det_score` | number | How confident Orbit is that the box holds a face, from 0 to 1. |

Orbit keeps the photo for 7 days. Detect a photo again to search with it after that.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `developer_v3_faces_image_required` | The request has no `image` field. |
| 413 | `face_image_too_large` | The photo is larger than 25 MB. |
| 422 | `developer_v3_faces_image_unusable` | The photo is smaller than 50 × 50 pixels or in another format. |
| 502 | `developer_v3_faces_upstream_failed` | Face detection is temporarily unavailable. Retry later. |

## Authentication and Cost

This endpoint requires `search:read`. Detecting faces is free.


## OpenAPI

````yaml openapi.json POST /v3/faces/detect
openapi: 3.1.0
info:
  title: Orbit API
  version: 3.0.0
  description: Search for people and enrich known Orbit profiles.
servers:
  - url: https://api.orbitsearch.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Search
    description: Find people and poll search results.
  - name: Enrich
    description: Read or enrich known Orbit profiles.
  - name: Watchers
    description: Watch a profile on a schedule and read what each run found.
  - name: Webhooks
    description: Register endpoints that receive signed event deliveries.
paths:
  /v3/faces/detect:
    post:
      tags:
        - Search
      summary: Detect Faces
      description: >-
        Store a photo privately and return every face in it, left to right.
        Requires the `search:read` scope.
      operationId: detectFaces
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - image
              properties:
                image:
                  type: string
                  format: binary
                  description: A JPG, PNG, or WebP photo from 50 × 50 pixels up to 25 MB.
      responses:
        '200':
          description: The stored photo and its faces.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceDetectionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          description: The photo is larger than 25 MB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The photo is too small or in another format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: Face detection is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    FaceDetectionResponse:
      type: object
      required:
        - status
        - payload
      description: The stored photo and its faces.
      properties:
        status:
          type: string
          enum:
            - success
        payload:
          $ref: '#/components/schemas/FaceDetection'
    ErrorResponse:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
          enum:
            - failed
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            requiredCredits:
              type: integer
              minimum: 0
              description: >-
                Credits required when the error is
                developer_api_credits_insufficient.
            remainingCredits:
              type: integer
              minimum: 0
              description: >-
                Available credits when the error is
                developer_api_credits_insufficient.
    FaceDetection:
      type: object
      required:
        - image_url
        - image_width
        - image_height
        - faces
      properties:
        image_url:
          type: string
          description: The reference to the stored photo.
        image_width:
          type:
            - integer
            - 'null'
        image_height:
          type:
            - integer
            - 'null'
        faces:
          type: array
          description: Every face in the photo, left to right.
          items:
            $ref: '#/components/schemas/DetectedFace'
    DetectedFace:
      type: object
      required:
        - index
        - bbox
        - det_score
      properties:
        index:
          type: integer
          minimum: 0
          description: The face's position in `faces`.
        bbox:
          $ref: '#/components/schemas/FaceBox'
        det_score:
          type: number
          minimum: 0
          maximum: 1
          description: How confident Orbit is that the box holds a face.
    FaceBox:
      type: array
      minItems: 4
      maxItems: 4
      items:
        type: number
        minimum: 0
      description: A face box `[x0, y0, x1, y1]` in the pixels of the upright photo.
      example:
        - 212
        - 140
        - 388
        - 356
  responses:
    BadRequest:
      description: The request is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The API key is missing or not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The API key does not have the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: The API key exceeded a rate limit.
      headers:
        Retry-After:
          description: Seconds to wait before another request.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Orbit API key
      description: Use an Orbit API key from the Developer Dashboard.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.