Anonymous Face Match Moderation

API Domain

Our API is designed to be used in two environments: a sandbox environment and a production environment.

The sandbox environment is intended for testing and development purposes, while the production environment is used for live data and real-world use cases.

To ensure the security and integrity of our API, we use separate API keys for each environment. This means that you will need to obtain different API keys for the sandbox and production environments, and should not use the same key for both.

Domain	Environment
https://faces.verifymycontent.com	faces collection production
https://faces-sdx.verifymycontent.com	faces collection sandbox
https://moderation.verifymycontent.com	moderation production
https://moderation.sandbox.verifymycontent.com	moderation sandbox

Generating the HMAC header

To improve the security of the communication between your implementation and the VerifyMyContent API, we require you to generate a unique hexadecimal encoded SHA256 HMAC hash for each request, based on the input parameters.

The process of generating it depends on the language of your implementation.

Example

SDKphpnode.jspythongo

If you use our SDK, the HMAC step will be abstracted,
and you don't need to do anything related to it.

Copied!

<?php

hash_hmac('sha256', $input, 'API_SECRET');

Copied!

import { HmacSHA256 } from 'crypto-js';

HmacSHA256(JSON.stringify(input), 'API_SECRET').toString()

Copied!

import hmac
import hashlib

def generateAuthHmacHeader(api_key, api_secret, request_body):
    sign_bytes = hmac.new(api_secret.encode('utf-8'), request_body.encode('utf-8'), hashlib.sha256).digest()
    sign_hex = sign_bytes.hex()
    authorization_header = f"hmac {api_key}:{sign_hex}"
    return authorization_header

Copied!

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
)

func generateAuthHmacHeader(apiKey, apiSecret, requestBody []byte]) string {
    hmac := hmac.New(sha256.New, []byte(apiSecret))
    h.Write(requestBody)

    signBytes := h.Sum(nil)

    signHex := hex.EncodeToString(signBytes)
    authorizationHeader := fmt.Sprintf("hmac %s:%s", apiKey, signHex)
    return authorizationHeader
}

Copied!

Faces collection

Insert a new face to a collection. If the collection is not created this endpoint will create a new one.

Only one face at a time can be added to a collection.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

collection_id required

The collection identifier you send to correlate with the moderation.

face_id required

The face identifier you send to correlate with the moderation.

face_image required

Base 64 for the image that is being sent for each face_id.

Response parameters

total_faces

The number of faces present in the collection.

Error responses

Code	Description
400	{"message": "field <field_name> not found", "status_code": 400} Copied!
400	{"message": "face_id cannot contain blank spaces", "status_code": 400} Copied!
422	{"message": "invalid parameter", "status_code": 422} Copied!
401	{"message": "invalid authorization", "status_code": 401} Copied!
401	{"message": "Missing Api Key", "status_code": 401} Copied!
409	{"message": "face id for this collection already exists", "status_code": 409} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurl

POST /v1/collections HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY

{
    "collection_id": "a499a08c-b7ed-43ad-99c4-b9ce0f8b4a35",
    "face_id": "d1dc9be3-9a4b-4df2-a7fc-dec03d36ad94",
    "face_image": "ZDFkYzliZTMtOWE0Yi00ZGYyLWE3ZmMtZGVjMDNkMzZhZDk0"
}

Copied!

curl  \
    -H 'Content-Type: application/json' \
    -H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY" \
    -X 'https://faces-sdx.verifymycontent.com/v1/collections'
    --data '{
        "collection_id": "a499a08c-b7ed-43ad-99c4-b9ce0f8b4a35",
        "face_id": "d1dc9be3-9a4b-4df2-a7fc-dec03d36ad94",
        "face_image": "ZDFkYzliZTMtOWE0Yi00ZGYyLWE3ZmMtZGVjMDNkMzZhZDk0"
    }'

Copied!

Response 201: (application/json)

{
  "total_faces": 0
}

Copied!

Get all faces from collection.

Returns the ids of all of the faces present in the collection.

Authorization Header

Generate HMAC with: Request URI
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Response parameters

face_ids

An array of ids of all of the faces added to the collection.

Error responses

Code	Description
401	{"message": "invalid authentication", "status_code": 401} Copied!
404	{"message": "no results found", "status_code": 404} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurl

GET /v1/collections/{collection_id} HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI

Copied!

curl --location --globoff 'https://faces-sdx.verifymycontent.com/v1/collections/{collection_id}'

Copied!

Response 200: (application/json)

{
  "face_ids": [
    "a54de98d-c139-45b7-97bf-7b525f19c794"
  ]
}

Copied!

Delete one face from collection.

Returns the number of faces left in the collection.

Authorization Header

Generate HMAC with: Request URI
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

collection_id

The collection identifier you send to correlate with the moderation.

face_id

Id of the face to be removed from the collection.

Response parameters

total_faces

The number of faces remaining in the collection.

Error responses

Code	Description
401	{"message": "invalid authentication", "status_code": 401} Copied!
403	{"message": "Permission denied", "status_code": 403} Copied!
404	{"message": "no results found", "status_code": 404} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurl

DELETE /v1/collections/{collection_id}/faces/{face_id} HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI

Copied!

curl --location --globoff --request DELETE 'https://faces-sdx.verifymycontent.com/v1/collections/{collection_id}/faces/{face_id}'

Copied!

Response 200: (application/json)

{
  "total_faces": 0
}

Copied!

Risky user faces collection

Insert new risky user faces to the collection (only one collection).

Only one face at a time can be added to a collection.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

face_id required

The face identifier you send to correlate with the moderation.

face_image required

Base 64 for the image that is being sent for each face_id.

Response parameters

total_faces

The number of faces present in the collection.

Error responses

Code	Description
400	{"message": "field <field_name> not found", "status_code": 400} Copied!
400	{"message": "face_id cannot contain blank spaces", "status_code": 400} Copied!
422	{"message": "invalid parameter", "status_code": 422} Copied!
401	{"message": "invalid authorization", "status_code": 401} Copied!
401	{"message": "Missing Api Key", "status_code": 401} Copied!
409	{"message": "face id for this collection already exists", "status_code": 409} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurl

POST /v1/collections/risky HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY

{
    "face_id": "d1dc9be3-9a4b-4df2-a7fc-dec03d36ad94",
    "face_image": "ZDFkYzliZTMtOWE0Yi00ZGYyLWE3ZmMtZGVjMDNkMzZhZDk0"
}

Copied!

curl -X POST 'https://faces-sdx.verifymycontent.com/v1/collections/risky'     -H 'Content-Type: application/json' \
    -H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY" \
    -d '{
        "face_id": "d1dc9be3-9a4b-4df2-a7fc-dec03d36ad94",
        "face_image": "ZDFkYzliZTMtOWE0Yi00ZGYyLWE3ZmMtZGVjMDNkMzZhZDk0"
    }'

Copied!

Response 201: (application/json)

{
  "total_faces": 0
}

Copied!

Get all risky user faces from the collection.

Returns the ids of all of the faces present in the collection.

Authorization Header

Generate HMAC with: Request URI
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Response parameters

face_ids

An array of ids of all of the faces added to the collection.

Error responses

Code	Description
401	{"message": "invalid authentication", "status_code": 401} Copied!
404	{"message": "no results found", "status_code": 404} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurl

GET /v1/collections/risky/ HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI

Copied!

curl --location --globoff 'https://faces-sdx.verifymycontent.com/v1/collections/risky'

Copied!

Response 200: (application/json)

{
  "face_ids": [
    "a54de98d-c139-45b7-97bf-7b525f19c794"
  ]
}

Copied!

Delete risky user faces from the collection.

Returns the number of faces left in the collection. Only one face at a time can be removed from a collection.

Authorization Header

Generate HMAC with: Request URI
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

face_id

Id of the face to be removed from the collection.

Response parameters

total_faces

The number of faces remaining in the collection.

Error responses

Code	Description
401	{"message": "invalid authentication", "status_code": 401} Copied!
403	{"message": "Permission denied", "status_code": 403} Copied!
404	{"message": "no results found", "status_code": 404} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurl

DELETE /v1/collections/risky/{face_id} HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI

Copied!

curl --location --globoff --request DELETE 'https://faces-sdx.verifymycontent.com/v1/collections/risky/{face_id}'

Copied!

Response 200: (application/json)

{
  "total_faces": 0
}

Copied!

Face match for Anonymous Content Moderation

Integration

When you call the Start Moderation endpoint, it will send the content to moderation, and you will receive the moderation status updates on the URL you've set as a webhook.

Alternatively, the Current status of the moderation endpoint is available for you to get the status, if you prefer not to use a webhook.

The meaning of each status

When you start the moderation, the content will have the status Awaiting Face match, which will trigger our AI to moderate the content and check that it does not contain any content that should not be published. If we cannot download the video or image you sent, the content will finish the process with the status Failed.

After the AI, the status will change to Awaiting Moderation, and the human moderation is triggered.

Once the content has passed human moderation, the status will change to Approved if the content can be published. Please check the warning section to see if any unexpected people were detected in the content.

Start Moderation

To start the moderation, you'll need to send us the original video or image uploaded by your customer and a webhook to notify you when the moderation status changes if you’ve chosen to use one.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

content required

Information about the content being moderated.

type optional

It can be video or image. Defaults to video.

external_id required

A unique identifier on your side to correlate with this moderation.

url required

The URL where we can download the original video or image uploaded by your customer.

title optional

The title of the content being moderated.

description optional

The text written by your customer to describe the content.

collection_id required

The collection identifier you send to correlate with the moderation. This field is required for face-match and combined types, except when risky faces are stored in the risky collection.

face_ids optional

An array of ids of the faces appearing in the content.

type optional

It can be one of these values. It defaults to moderation.

Type	Description
moderation	We will look for any illegal harmful content. This is also the default option when you don’t send any value.
face-match	We will look to see if the expected people are present in the content.
combined	We will look for any illegal harmful content and to see if the expected people are present in the content via face-match.

redirect_url optional

The URL where we are going to redirect your customer after the moderation is done.

webhook required

This is the URL where we are going to post status updates of the moderation.

Response parameters

id

Unique identifier generated by the VerifyMyContent API

redirect_url

URL you’ll need to redirect the user to start the moderation process

external_id

The unique identifier you have sent to correlate this moderation

status

It represents the current status of the moderation flow. It can be one of the following:

Status	Description
Awaiting Face match	Our AI is about to process the content to detect any person who should not be in the content.
Awaiting Moderation	The moderators are about to confirm the moderation decision.
Approved	All participants consented to the publishing of the content. Please check the warning section to see if any unexpected people were detected in the content.
Failed	An error occurred during the content processing.

notes

Any notes associated with the moderation.

tags

Any tags associated with the moderation when a face match warning is found.

created_at

The date and time in the UTC timezone when the moderation was created

updated_at

The date and time in the UTC timezone when the moderation was updated

Error responses

Code	Description
400	{"message": "field <field_name> not found", "status_code": 400} Copied!
400	{"message": "collection_id is invalid", "status_code": 400} Copied!
400	{"message": "collection_id is required for face match | combined type", "status_code": 400} Copied!
400	{"message": "collection_id is required when face_ids are sent", "status_code": 400} Copied!
400	{"message": "collection_id is required when no risky faces are stored in the risky collection", "status_code": 400} Copied!
400	{"message": "collection [YOUR_COLLECTION_ID] has no faces registered", "status_code": 400} Copied!
400	{"message": "face ids [FACE_ID_1 FACE_ID 2] are invalid for collection YOUR_COLLECTION_ID", "status_code": 400} Copied!
422	{"message": "invalid parameter", "status_code": 422} Copied!
401	{"message": "invalid authorization", "status_code": 401} Copied!
401	{"message": "Missing Api Key", "status_code": 401} Copied!
403	{"message": "access denied", "status_code": 403} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurl

POST /api/v1/moderation-anonymous HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY

{
    "content": {
        "type": "video",
        "external_id": "YOUR-VIDEO-ID",
        "url": "https://example.com/video.mp4",
        "title": "Your title",
        "description": "Your description"
    },
    "collection_id": "0910abd9-0507-4f7c-9ddf-e3b52b042472",
    "face_ids": ["a54de98d-c139-45b7-97bf-7b525f19c794"],
    "type": "face-match",
    "rule": "default", 
    "webhook": "https://example.com/webhook",
    "redirect_url": "https://app.verifymycontent.com/v/ABC-123-5678-ABC"
}

Copied!

curl -d '{"content": {"type": "video", "external_id": "YOUR-VIDEO-ID", "url": "https://example.com/video.mp4", "title": "Your title", "description": "Your description"}, "webhook": "https://example.com/webhook", "face_ids": ["a54de98d-c139-45b7-97bf-7b525f19c794"], "collection_id": "0910abd9-0507-4f7c-9ddf-e3b52b042472", "type": "moderation", "rule": "default", "redirect_url": "https://app.verifymycontent.com/v/ABC-123-5678-ABC"}' \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY" \
-X POST https://moderation.sandbox.verifymycontent.com/api/v1/moderation

Copied!

Response 201: (application/json)

{
  "id": "ABC-123-5678-ABC",
  "external_id": "YOUR-VIDEO-ID",
  "status": "Awaiting Face Match",
  "notes": "",
  "tags": null,
  "created_at": "2020-11-12 19:06:00",
  "updated_at": "2020-11-12 19:06:00"
}

Copied!

Get current status of the moderation

When you already have the id of a moderation you can see the current details of the moderation.

Authorization Header

Generate HMAC with: Request URI
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Response parameters

id

Unique identifier generated by the VerifyMyContent API

redirect_url

URL you’ll need to redirect the user to start the moderation process

external_id

The unique identifier you have sent to correlate this moderation

status

It represents the current status of the moderation flow. It can be one of the following:

Status	Description
Awaiting Face match	Our AI is about to process the content to detect any person who should not be in the content.
Awaiting Moderation	The moderators are about to confirm the moderation decision.
Approved	All participants consented to the publishing of the content. Please check the warning section to see if any unexpected people were detected in the content.
Failed	An error occurred during the content processing.

notes

Any notes associated with the moderation.

facematch

It represents the results of the face match moderation. It can be the following:

Status	Description
Known	An array of face_ids that contain the expected faces seen in the content.
Unknown	An array of objects that contain the bounding box and the time when the unexpected face was seen in the content.
Risky	An array of objects that contain the face_id, bounding box and the time when the risky user face was seen in the content.

tags

Any tags associated with the moderation when a face match warning is found.

created_at

The date and time in the UTC timezone when the moderation was created

updated_at

The date and time in the UTC timezone when the moderation was updated

Error responses

Code	Description
401	{"message": "invalid authentication", "status_code": 401} Copied!
403	{"message": "Permission denied", "status_code": 403} Copied!
404	{"message": "no results found", "status_code": 404} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurlphp

GET /api/v1/moderation/{ID} HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI

Copied!

curl -H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI" \
https://moderation.sandbox.verifymycontent.com/api/v1/moderation/{ID}

Copied!

<?php
require(__DIR__ . "/vendor/autoload.php");

use \VerifyMyContent\VideoModeration\Moderation;

$moderation = new Moderation(getenv('VMC_API_KEY'), getenv('VMC_API_SECRET'));
//$moderation->useSandbox();

$response = $moderation->get('ID');

Copied!

Response 200: (application/json)

{
  "id": "ABC-123-5678-ABC",
  "redirect_url": "",
  "external_id": "YOUR-CORRELATION-ID",
  "status": "Approved",
  "notes": "",
  "facematch": {
    "known": [
      "010203"
    ],
    "participant": [],
    "unknown": [
      {
        "face_id": "",
        "time": 1,
        "bounding_box": {
          "x": 2123,
          "y": 1230,
          "height": 123,
          "width": 123
        }
      }
    ],
    "risky": [
      {
        "face_id": "John Doe",
        "time": 1,
        "bounding_box": {
          "x": 2123,
          "y": 1230,
          "height": 123,
          "width": 123
        }
      }
    ]
  },
  "tags": [
    "UNKNOWN_PERSON",
    "RISKY_USER"
  ],
  "created_at": "2020-11-12 19:06:00",
  "updated_at": "2020-11-12 19:06:00"
}

Copied!

Receive the current status of the moderation

The same information that you can get on the moderation detail API can also be sent via webhook to your domain if you send it to us when you create a moderation.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

id

Unique identifier generated by the VerifyMyContent API

redirect_url

URL you’ll need to redirect the user to start the moderation process

external_id

The unique identifier you have sent to correlate this moderation

status

It represents the current status of the moderation flow. It can be one of the following:

Status	Description
Awaiting Face match	Our AI is about to process the content to detect any person who should not be in the content.
Awaiting Moderation	The moderators are about to confirm the moderation decision.
Approved	All participants consented to the publishing of the content. Please check the warning section to see if any unexpected people were detected in the content.
Failed	An error occurred during the content processing.

notes

Any notes associated with the moderation.

facematch

It represents the results of the face match moderation. It can be the following:

Status	Description
Known	An array of face_ids that contain the expected faces seen in the content.
Unknown	An array of objects that contain the bounding box and the time when the unexpected face was seen in the content.
Risky	An array of objects that contain the face_id, bounding box and the time when the risky user face was seen in the content.

tags

Any tags associated with the moderation when a face match warning is found.

created_at

The date and time in the UTC timezone when the moderation was created

updated_at

The date and time in the UTC timezone when the moderation was updated

Webhook Call

httpcurl

POST /your-path HTTP/1.1
Host: https://your-domain.com
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY

{
    "id": "ABC-123-5678-ABC",
    "external_id": "YOUR-CORRELATION-ID",
    "status": "Approved",
    "notes": "",
    "facematch": {
        "known": ["010203"],
        "participant": [],
        "unknown": [
            {
                "face_id": "",
                "time": 1,
                "bounding_box": {
                    "x": 2123,
                    "y": 1230,
                    "height" : 123,
                    "width": 123,
                }
            }
        ],
        "risky": [
            {
                "face_id": "John Doe",
                "time": 1,
                "bounding_box": {
                    "x": 2123,
                    "y": 1230,
                    "height" : 123,
                    "width": 123,
                }
            }
        ],
    },
    "tags": [
      "UNKNOWN_PERSON",
      "RISKY_USER"
    ],
    "created_at": "2020-11-12 19:06:00",
    "updated_at": "2020-11-12 19:06:00",
}

Copied!

curl -d '{"id": "ABC-123-5678-ABC", "external_id": "YOUR-CORRELATION-ID", "status": "Rejected", "notes": "Harmful content found.", "tags": ["UNDERAGE"], "created_at": "2020-11-12 19:06:00", "updated_at": "2020-11-12 19:06:00"}' \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY" \
-X POST https://your-domain.com/your-path

Copied!

Response 2xx

Face match for Anonymous Live Stream Moderation

Integration Steps

Our content moderation system is fully automated and requires no manual intervention or input from the user. The moderation process is performed entirely in the backend using browser automation technology allowing us to analyse and filter content at scale. When content is submitted for moderation, our system ingests it automatically and analyses it using a combination of machine learning algorithms and human-defined rules. The system then applies a series of filters to identify any content that violates our guidelines.

VerifyMyContent anonymous live stream moderation consists of 2 basic steps:

1st

Creating the livestream.

2nd

Handling the webhook messages.

1. Creating the livestream

Using the anonymous moderation flow, your users don't need to authenticate with VerifyMyContent, only the video broadcast will be moderated.

Before calling this endpoint, make sure your user is ready to broadcast, because our AI will attempt to start the moderation right away.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

external_id required

The unique identifier you send to correlate with the moderation.

embed_url required

The URL where VerifyMyContent can watch the stream without an account on your site.

Important: Make sure this URL doesn't have any popups and/or ads that will overlap the video that will be watched by our moderation team.

title optional

The title of the content being moderated.

description optional

The text written by your customer to describe the content.

webhook required

The URL where we will post status updates on the moderation.

stream required

The technology used by the Livestream.

protocol required

One of rtmps, hls or webrtc.

url required

We must always have access to the stream url.

Therefore, if your stream is private and depends on login using a username and password we must have access via a secret or signed url. Important: If you're struggling with this step, you can head to the troubleshooting section for more guidance.

The URL pointing to your stream has different validation rules based on the protocol you are using:

RTMPS Example: rmtps://example.com:5443

HLS It must point to an m3u8 file where we'll be able to retrieve the stream. Example: https://example.com/file.m3u8

WebRTC It must point to an embedded version of the stream. Example: https://example.com/embed-url

rule optional

It can be one of the values:

Rule	Description
default	It will look for content that is not allowed in the context of adult websites. This is also the default option when you don't send any value.
no-nudity	It will look for both content not allowed in the context of adult websites, but will also look for nudity.

collection_id required

The collection identifier you send to correlate with the moderation. This field is required for face-match and combined types, except when risky faces are stored in the risky collection.

face_ids optional

An array of ids of the faces appearing in the content.

type optional

It can be one of these values. It defaults to moderation.

Type	Description
moderation	We will look for any illegal harmful content. This is also the default option when you don’t send any value.
face-match	We will look to see if the expected people are present in the content.
combined	We will look for any illegal harmful content and to see if the expected people are present in the content via face-match.

customer required

Customer information

id required

Customer's unique ID

email required

Customer's email address

phone optional

Customer's phone number

Response parameters

id

The unique identifier generated by the VerifyMyContent API.

external_id

The unique identifier you send to correlate with the moderation.

status

The current status of the moderation flow:

Status	Description
Started	The moderation process has started to detect any illegal or non-consensual content
Finished	The live stream has ended and no issues were found
Failed	An error occurred during the processing of the live stream

notes

Any notes associated with the moderation.

tags

Any tags associated with the moderation when a face match warning is found.

created_at

The date and time in the UTC timezone when the livestream was created

updated_at

The date and time in the UTC timezone when the livestream was updated

Error responses

Code	Description
400	{"message": "the request could not be understood by the server due to malformed syntax", "status_code": 400} Copied!
400	{"message": "collection_id is invalid", "status_code": 400} Copied!
400	{"message": "collection_id is required for face match | combined type", "status_code": 400} Copied!
400	{"message": "collection_id is required when face_ids are sent", "status_code": 400} Copied!
400	{"message": "collection_id is required when no risky faces are stored in the risky collection", "status_code": 400} Copied!
400	{"message": "collection [YOUR_COLLECTION_ID] has no faces registered", "status_code": 400} Copied!
400	{"message": "face ids [FACE_ID_1 FACE_ID 2] are invalid for collection YOUR_COLLECTION_ID", "status_code": 400} Copied!
401	{"message": "invalid authentication", "status_code": 401} Copied!
422	{"message": "invalid parameters", "status_code": 422} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurlphp

POST /api/v1/livestream-anonymous HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY

{
    "external_id": "YOUR-LIVESTREAM-ID",
    "embed_url": "https://example.com/live-stream-embed",
    "title": "Your title",
    "description": "Your description",
    "stream": {
        "protocol": "rtmps",
        "url": "rtmps://your-server:443/your-video-stream"
    },
    "collection_id": "0910abd9-0507-4f7c-9ddf-e3b52b042472",
    "face_ids": ["a54de98d-c139-45b7-97bf-7b525f19c794"],
    "type": "face-match",
    "rule": "default", 
    "customer": {
        "id": "YOUR-USER-ID",
        "email": "[email protected]",
        "phone": "+4412345678"
    },
    "webhook": "https://example.com/webhook"
}

Copied!

curl -d '{"external_id": "YOUR-LIVESTREAM-ID", "rule": "default", "embed_url": "https://example.com/live-stream-embed", "title": "Your title", "description": "Your description", "stream": {"protocol": "rtmps", "url": "rtmps://your-server:443/your-video-stream"}, "webhook": "https://example.com/webhook", "face_ids": ["a54de98d-c139-45b7-97bf-7b525f19c794"], "collection_id": "0910abd9-0507-4f7c-9ddf-e3b52b042472", "type": "moderation", "rule": "default", "customer": {"id": "YOUR-USER-ID", "email": "[email protected]", "phone": "+4412345678"}}' \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY" \
-X POST https://moderation.sandbox.verifymycontent.com/api/v1/livestream

Copied!

<?php
require(__DIR__ . "/vendor/autoload.php");

use \VerifyMyContent\VideoModeration\Moderation;
use \VerifyMyContent\SDK\ContentModeration\Entity\Requests\CreateLiveContentModerationRequest;

$moderation = new Moderation(getenv('VMC_API_KEY'), getenv('VMC_API_SECRET'));
//$moderation->useSandbox();

$response = $moderation->createAnonymousLivestream(new CreateLiveContentModerationRequest([
  "external_id" => "YOUR-LIVESTREAM-ID",
  "embed_url" => "https://example.com/live/",
  "title" => "Live stream title",
  "description" => "Live stream description",
  "webhook" => "https://example.com/webhook",
  "stream" => [
      "protocol" => "webrtc",
      "url" => "https://example.com/live/",
  ],
  "rule" => "default",
  "collection_id" => "0910abd9-0507-4f7c-9ddf-e3b52b042472",
  "face_ids" => ["a54de98d-c139-45b7-97bf-7b525f19c794"],
  "type" => "moderation",
  "customer" => [
      "id" => "YOUR-CUSTOMER-UNIQUE-ID",
      "email" => "[email protected]",
      "phone" => "+4412345678"
  ]
]));

Copied!

Response 201: (application/json)

{
  "id": "ABC-123-5678-ABC",
  "external_id": "YOUR-CORRELATION-ID",
  "status": "Started",
  "notes": "",
  "tags": null,
  "created_at": "2020-11-12 19:06:00",
  "updated_at": "2020-11-12 19:06:00"
}

Copied!

2. Handling the webhook messages

During the broadcast, our AI and moderation team will be monitoring the video looking for the people listed are currently present on livestream. In this case, you’ll receive a webhook in one of 2 situations:

1. When all the people listed are currently present on livestream.
2. When a face match warning is found, we’ll notify you so you can take action.

We’ll send the same JSON as the Request body of the webhook that we return as the Response Body when you start a live stream.

In the same way that you send an HMAC header during the requests, we’ll be sending it to your webhook so you can confirm that we have sent the request.

Response

You’ll need to return any of the 200, 201, or 204 status codes.

Any different status code will be interpreted as you couldn’t handle the webhook, and we’ll try 3 more times in the proceeding minutes.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

id

The unique identifier generated by the VerifyMyContent API.

title

The title of the content being moderated.

description

The text written by your customer to describe the content.

login_url

The URL you’ll need to redirect the user to confirm ownership.

external_id

The unique identifier you send to correlate with the moderation.

notes

Any notes associated with the moderation.

tags

Any tags associated with the moderation when a face match warning is found.

facematch

It represents the results of the face match moderation. It can be the following:

Status	Description
Known	An array of face_ids that contain the expected faces seen in the content.
Unknown	An array of objects that contain the bounding box and the time when the unexpected face was seen in the content.
Risky	An array of objects that contain the face_id, bounding box and the time when the risky user face was seen in the content.

created_at

The date and time in the UTC timezone when the livestream was created

updated_at

The date and time in the UTC timezone when the livestream was updated

status

The current status of the moderation flow. It will change depending on the step of the live stream moderation.

Moderating the content

Status	Description
Started	The moderation process has started to detect any illegal or non-consensual content
Finished	The live stream has ended and no issues were found
Failed	An error occurred during the processing of the live stream

Pause live stream

Status	Description
Pause Requested	The live stream was requested to be paused
Paused	The moderation process has paused
Resume Requested	The live stream was requested to be resumed
Resumed	The moderation process has been resumed
Finished due to Inactivity	The moderation was stopped after being paused for too long (10+ hours)

Webhook Call

httpcurl

POST /your-path HTTP/1.1
Host: https://your-domain.com
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY
{
    "id": "ABC-123-5678-ABC",
    "external_id": "YOUR-CORRELATION-ID",
    "status": "Started",
    "notes": "",
    "facematch": {
        "known": ["010203"],
        "participant": [],
        "unknown": [
            {
                "face_id": "",
                "time": 1,
                "bounding_box": {
                    "x": 2123,
                    "y": 1230,
                    "height" : 123,
                    "width": 123,
                }
            }
        ],
        "risky": [
            {
                "face_id": "John Doe",
                "time": 1,
                "bounding_box": {
                    "x": 2123,
                    "y": 1230,
                    "height" : 123,
                    "width": 123,
                }
            }
        ],
    },
    "tags": [
        "UNKNOWN_PERSON",
        "RISKY_USER"
    ],
    "created_at": "2020-11-12 19:06:00",
    "updated_at": "2020-11-12 19:06:00",
    "type": "face-match"
}

Copied!

curl -d '{"id": "ABC-123-5678-ABC", "external_id": "YOUR-CORRELATION-ID", "status": "Rejected", "notes": "Harmful content found.", "tags": ["UNDERAGE"], "created_at": "2020-11-12 19:06:00", "updated_at": "2020-11-12 19:06:00"}' \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY" \
-X POST https://your-domain.com/your-path

Copied!

Response 200, 201 or 204

Get current status of the livestream

When you already have the id of a livestream you can see the current details of the livestream.

Authorization Header

Generate HMAC with: Request URI
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Response parameters

id

The unique identifier generated by the VerifyMyContent API.

title

The title of the content being moderated.

description

The text written by your customer to describe the content.

login_url

The URL you’ll need to redirect the user to confirm ownership.

external_id

The unique identifier you send to correlate with the moderation.

notes

Any notes associated with the moderation.

tags

Any tags associated with the moderation when a face match warning is found.

facematch

It represents the results of the face match moderation. It can be the following:

Status	Description
Known	An array of face_ids that contain the expected faces seen in the content.
Unknown	An array of objects that contain the bounding box and the time when the unexpected face was seen in the content.
Risky	An array of objects that contain the face_id, bounding box and the time when the risky user face was seen in the content.

created_at

The date and time in the UTC timezone when the livestream was created

updated_at

The date and time in the UTC timezone when the livestream was updated

status

The current status of the moderation flow. It will change depending on the step of the live stream moderation.

Moderating the content

Status	Description
Started	The moderation process has started to detect any illegal or non-consensual content
Finished	The live stream has ended and no issues were found
Failed	An error occurred during the processing of the live stream

Pause live stream

Status	Description
Pause Requested	The live stream was requested to be paused
Paused	The moderation process has paused
Resume Requested	The live stream was requested to be resumed
Resumed	The moderation process has been resumed
Finished due to Inactivity	The moderation was stopped after being paused for too long (10+ hours)

Response 200: (application/json)

{
  "id": "ABC-123-5678-ABC",
  "title": "livestream title",
  "description": "livestream description",
  "login_url": "",
  "external_id": "YOUR-CORRELATION-ID",
  "status": "Started",
  "notes": "",
  "facematch": {
    "known": [
      "010203"
    ],
    "participant": [],
    "unknown": [
      {
        "face_id": "",
        "time": 1,
        "bounding_box": {
          "x": 2123,
          "y": 1230,
          "height": 123,
          "width": 123
        }
      }
    ],
    "risky": [
      {
        "face_id": "John Doe",
        "time": 1,
        "bounding_box": {
          "x": 2123,
          "y": 1230,
          "height": 123,
          "width": 123
        }
      }
    ]
  },
  "tags": [
    "UNKNOWN_PERSON",
    "RISKY_USER"
  ],
  "created_at": "2020-11-12 19:06:00",
  "updated_at": "2020-11-12 19:06:00",
  "type": "face-match"
}

Copied!

Updating Live Stream moderation rules

This endpoint allows you to update the moderation rules for a specific live stream. By default, all live streams are moderated using a set of predefined rules that are designed to minimize the risk of harmful or offensive content being broadcast to viewers. However, there may be cases where you need to include aditional rules to suit your business requirements.

Example: You can create a livestream with the 'no-nudity' rule, but after a couple of minutes, send a PATCH request to change it to the 'default' rules depending on the privacy level of this broacast.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

rule required

It can be one of the values:

Rule	Description
default	It will look for content that is not allowed in the context of adult websites. This is also the default option when you don't send any value.
no-nudity	It will look for both content not allowed in the context of adult websites, but will also look for nudity.

Error responses

Code	Description
400	{"message": "Invalid rule", "status_code": 400} Copied!
401	{"message": "invalid authentication", "status_code": 401} Copied!
404	{"message": "no results found", "status_code": 404} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurl

PATCH /api/v1/livestream/{ID}/rule HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY

{
    "rule": "default"
}

Copied!

curl -d '{"rule": "default"}' \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY" \
-X PATCH https://moderation.sandbox.verifymycontent.com/api/v1/livestream/{ID}/rule

Copied!

Response 204

Pausing Live Stream moderation

This endpoint allows you to pause the moderation for a specific live stream.

Example: If your live stream has a pause feature, use this endpoint to pause the moderation until the live stream resumes.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

id required

The ID of the Live stream to be paused.

Error responses

Code	Description
401	{"message": "invalid authentication", "status_code": 401} Copied!
404	{"message": "no results found", "status_code": 404} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurlphp

PATCH /api/v1/livestream/{ID}/pause HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI

Copied!

curl -H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI" \
-X PATCH https://moderation.sandbox.verifymycontent.com/api/v1/livestream/{ID}/pause

Copied!

<?php
require(__DIR__ . "/vendor/autoload.php");

use \VerifyMyContent\VideoModeration\Moderation;

$moderation = new Moderation(getenv('VMC_API_KEY'), getenv('VMC_API_SECRET'));
//$moderation->useSandbox();

$moderation->pauseLivestream("YOUR-LIVESTREAM-ID");

Copied!

Response 204

Resuming Live Stream moderation

This endpoint allows you to resume the moderation for a specific live stream.

Authorization Header

Generate HMAC with: Request URI
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

id required

The ID of the live stream to be resumed.

Error responses

Code	Description
401	{"message": "invalid authentication", "status_code": 401} Copied!
404	{"message": "no results found", "status_code": 404} Copied!
500	{"message": "Internal Server Error","status_code": 500} Copied!

API Call

httpcurl

PATCH /api/v1/livestream/{ID}/resume HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI

Copied!

curl -X PATCH https://moderation.sandbox.verifymycontent.com/api/v1/livestream/{ID}/resume \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI"

Copied!

Response 204

Troubleshooting

The video on my website can only be viewed by a logged-in user

For our AI and team of Moderators to be able to watch your videos, you'll need to provide us with a URL that can be accessed without a username and password.

To do this, you can use a signed URL that will skip your default authentication system whilst still restricting access and keeping the URL secure.

When you sign an URL, it adds new query parameters to the original URL. One of them will be a signature generated based on the URL and a secret only your website will have. This way, only your website could generate and validate it later.

Some frameworks like Laravel already provide helper functions for you to sign a url.

We've created an example of an express.js application that signs and validates a URL using the signed-url npm package in the following repository: https://github.com/verifymycontent/sign-url-example.