▣ ARTIFICIAL INTELLIGENCE · IMAGE PROCESSING

AI Video Person Detection API

Hosted on ApyHub

What it does

Person Detection identifies people in video or image files and returns the result from either Azure or Google processing, depending on the service you request. Send a file or a URL, choose requested_service, and get the structured detection output back in the data object.

Use the /url endpoint when your media is already hosted, or /file when you want to upload it directly. The URL route accepts url plus requested_service, and can also take Azure connection details (region, account_id, access_token) or Google credentials (google_language, google_credential_json). The file route accepts file plus requested_service, with Azure fields split into azure_region, azure_account_id, and azure_access_token, or a google_credential_file upload for Google routes.

This is useful when you need to flag frames or assets that contain people, such as moderation pipelines, media indexing, or video analysis workflows. The response is returned under data, with either an azure or google object present depending on the provider you selected.

Because the provider-specific payload is passed through in the response, you can integrate Person Detection into existing Azure- or Google-based processing without translating the result into a different schema.

Provider (requested_service)	Atoms
Azure	500
Google	500

▣ ENDPOINT 01 / 02

POST

Person Detection via URL

http://localhost:8080/apyhub/detect-persons/url

QUICKSTARTGUIDE

Quickstart

Send the video URL and choose the detection service to get a person-detection result.

curl -X POST "http://localhost:8080/apyhub/detect-persons/url" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://assets.apyhub.com/samples/sample.mp4",
    "requested_service": "azure",
    "azure": {
        "access_token": "your-access_token",
        "account_id": "your-account_id",
        "region": "your-region"
    }
  }'

What you'll get back

Returns a JSON object with a data object field. The data object may include an azure object when requested_service is azure, or a google object when requested_service is google.

{
  "data": {
    "azure": {}
  }
}

TRY ITLIVE · 500 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Detects persons in a media file provided by URL and returns a JSON object with a data object containing either an azure or google result, depending on the requested service.

Request Body

Parameter	Type	Mandatory	Description
url	String	Yes	Media URL to analyze. Must be a URI.
azure	Object	No	Azure-specific configuration object. Include the fields below when using Azure.
azure.region	String	No	Azure region.
azure.account_id	String	No	Azure account ID.
azure.access_token	String	No	Azure access token.
google	Object	No	Google-specific configuration object. Include the fields below when using Google.
google.google_language	String	No	Google language code.
google.google_credential_json	Object	No	Google Cloud service account JSON. The schema defines nested credential fields, but only one level is documented here; see schema for nested fields.
requested_service	ENUM	Yes	Service to use. Allowed values: `azure`, `google`.

Response

Returns a JSON object with a required data object field. The data object may include an azure object when requested_service is azure, or a google object when requested_service is google.

Parameter	Type	Mandatory	Description
data	Object	Yes	Wrapper object for the detection result.
data.azure	Object	No	Present when `requested_service` is `azure`. Additional properties are allowed.
data.google	Object	No	Present when `requested_service` is `google`. Additional properties are allowed.

Body

Name

Type

Description

bodyREQUIRED

object

—

▣ ENDPOINT 02 / 02

POST

Person Detection via file upload

http://localhost:8080/apyhub/detect-persons/file

QUICKSTARTGUIDE

Quickstart

Upload an image and choose the backend service to detect persons.

curl -X POST "http://localhost:8080/apyhub/detect-persons/file" \
  -H "apy-token: $APY_TOKEN" \
  -F "file=@/path/to/image.jpg" \
  -F "requested_service=azure" \
  -F 'azure_access_token="your-azure_access_token"' \
  -F 'azure_account_id="your-azure_account_id"' \
  -F 'azure_region="your-azure_region"'

What you'll get back

Returns a JSON object with a data object. The data object can include an azure object when requested_service is azure, or a google object when requested_service is google.

{
  "data": {
    "azure": {}
  }
}

TRY ITLIVE · 500 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Uploads a file to run person detection using either the Azure or Google route, based on requested_service. The response is a JSON object containing a data object with a service-specific result object for the selected provider.

Request Body

Parameter	Type	Mandatory	Description
file	String	Yes	File to analyze, sent as binary (`format: binary`).
azure_region	String	No	Azure region. Example: `trial`.
azure_account_id	String	No	Azure account identifier.
requested_service	ENUM	Yes	Service route to use. Allowed values: `azure`, `google`. Example: `azure`.
azure_access_token	String	No	Azure access token.
google_credential_file	String	No	Google service account JSON, sent as binary (`format: binary`).

Response

Returns a JSON object with a required data object field. Inside data, the schema may include an azure object when requested_service is azure, or a google object when requested_service is google.

Parameter	Type	Mandatory	Description
data	Object	Yes	Response wrapper object. May contain provider-specific result data.
data.azure	Object	No	Present when `requested_service` is `azure`. Additional properties are allowed.
data.google	Object	No	Present when `requested_service` is `google`. Additional properties are allowed.

Body

Name

Type

Description

bodyREQUIRED

object

—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.