{ "openapi": "3.0.0", "info": { "title": "identifAI API", "version": "1.0.0", "description": "API for integrating identifAI's image and video classification capabilities.
**How to obtain your API Key**To obtain your API key, follow these simple steps:

  1. **Create a user profile and log in to the platform**

    If you don't have an account yet, visit our platform and create a user profile. Once you've completed registration and verified your email, log in with your credentials.

  2. **Access the user menu**

    After logging in, click on your name or the user icon in the top-right corner of the screen.

  3. **Select the API Key option**

    In the dropdown menu that appears, select the \"API Key\" option. From there, you can view or generate your API key.
Now you are ready to use your API key in our API!
**How to use the API**To use the API, first make a **POST** request to start the classification. Then, use the provided ***identifier*** from the **POST** request to retrieve the results.\n
\n**1. Image Classification**\n * To classify an image, you need to make a **POST** request to `/api/classification` with the required parameters (for details on the parameters, refer to the *\"Classification\"* section below).\n * In the response, you will receive the ***identifier*** of the classified image.\n * Use the provided ***identifier*** to retrieve the classification results by making a **GET** request to `/api/classification/{identifier}` (for details on how to structure this request, see the *\"Classification\"* section below).\n * The response will contain the classification results for the image in JSON format.
In the response, you will find a ***results*** array, which includes the classification results for each model used, and a ***verdicts*** array, which contains the results for each heuristic applied.
If the classification is not yet complete, continue sending the **GET** request until the result is available.
**2. Video Classification**\n * To classify a video, you need to make a **POST** request to `/api/classification_video` with the required parameters (for details on the parameters, refer to the *\"Classification\"* section below).\n * In the response, you will receive the ***identifier*** of the classified video.\n * Use the provided ***identifier*** to retrieve the classification results by making a **GET** request to `/api/classification_video/{identifier}` (for details on how to structure this request, see the *\"Classification\"* section below).\n * The response will provide the classification results for the video in JSON format. For video classification, the video is divided into *frames*.
In the response, you will find a ***results*** array that includes the classification outcomes for each model applied to each analyzed frame, and a ***verdicts*** array containing the results for each heuristic used.
If the classification is not complete, continue sending the **GET** request until the final results are returned.
**3. All Classifications**The `/api/classifications` endpoint will return all the image classifications made by a user. This will list the results of all past image classification requests.
**4. User Management** The **POST** `/api/user` endpoint allows you to create a user, while the **DELETE** `/api/user` endpoint is used to delete a user (For the structure of the requests, see more in the user section below).
" }, "servers": [ { "url": "https://backend.identifai.net" } ], "tags": [ { "name": "Classification", "description": "Classification routes" }, { "name": "Infrastructure", "description": "Infrastructure routes" }, { "name": "User", "description": "User actions" }, { "name": "Partner", "description": "Partner actions" } ], "paths": { "/api/classifications": { "get": { "summary": "Get multiple image classifications results", "description": "Retrieve multiple image classification results by providing a list of identifiers.\n\n**Note:** This endpoint also has an alias available at `/api/classifications_image`.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "identifiers", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "description": "A list of identifiers to retrieve classifications for." } ], "responses": { "200": { "description": "A list of classifications.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ImageResponse" } } } } }, "400": { "description": "Missing identifiers or too many identifiers.", "content": { "application/json": { "examples": { "missing_identifiers": { "value": { "error": { "identifiers": [ "The identifiers field is required" ] } } }, "too_many_identifiers": { "value": { "error": { "identifiers": [ "The identifiers may not have more than 100 items" ] } } } } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/classifications_video": { "get": { "summary": "Get multiple video classifications results", "description": "Retrieve multiple video classification results by providing a list of identifiers.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "identifiers[]", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "description": "A list of identifiers to retrieve classifications for." } ], "responses": { "200": { "description": "A list of video classifications.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VideoResponse" } } } } }, "400": { "description": "Missing identifiers or too many identifiers.", "content": { "application/json": { "examples": { "missing_identifiers": { "value": { "error": { "identifiers": [ "The identifiers field is required" ] } } }, "too_many_identifiers": { "value": { "error": { "identifiers": [ "The identifiers may not have more than 100 items" ] } } } } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/classifications_audio": { "get": { "summary": "Get multiple audio classifications results", "description": "Retrieve multiple audio classification results by providing a list of identifiers.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "identifiers[]", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "description": "A list of identifiers to retrieve classifications for." } ], "responses": { "200": { "description": "A list of audio classifications.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AudioResponse" } } } } }, "400": { "description": "Missing identifiers or too many identifiers.", "content": { "application/json": { "examples": { "missing_identifiers": { "value": { "error": { "identifiers": [ "The identifiers field is required" ] } } }, "too_many_identifiers": { "value": { "error": { "identifiers": [ "The identifiers may not have more than 100 items" ] } } } } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/classification": { "post": { "summary": "Classify an image", "description": "Submit an image to be classified as human or artificial.\n\nšŸ” Response format varies based on the `Accept` header:\n\n`Accept: application/json` ā†’ `{ \"identifier\": \"...\" }`\n\n Other values (e.g. `text/plain`) ā†’ plain text with just the identifier string.\n\n**Note:** This endpoint also has an alias available at `/api/classification_image`.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Accept", "in": "header", "description": "Response content type. Supported: application/json, text/plain.", "required": false, "schema": { "type": "string", "enum": [ "application/json", "text/plain" ] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "The image to be classified. **Supported formats:** PNG, JPEG, JPG, WebP, TIF, TIFF. **MIME types:** image/png, image/jpeg, image/jpg, image/webp, image/tif, image/tiff. **Maximum file size:** 15MB." }, "ref_id": { "type": "string", "description": "An optional reference ID to associate with the classification request." }, "with_morphing": { "type": "boolean", "description": "Set it to true if you also want to analyze people's faces in the image using morphing." }, "with_tampering": { "type": "boolean", "description": "Set it to true if you also want to analyze signs of tampering or manipulation without the aid of a Generative AI" }, "with_heatmap": { "type": "boolean", "description": "Set it to true if you also want to get an AI content heatmap." }, "webhook_url": { "type": "string", "description": "If specified, the classification result will also be automatically sent to the entered URL. Otherwise, the result can be obtained by polling the [relative endpoint](./get-classification-result). Please note that in order to use a webhook callback URL **you need to request a specific enablement**, otherwise the parameter is ignored. Moreover, the system may cache the analysis results of repeated submissions, i.e. submissions of the same file with the same options: in this case the webhook won't be called and the results would be accessible only by polling the [relative endpoint](./get-classification-result)." }, "no_cache": { "type": "boolean", "description": "Set it to true to force the system to reprocess the image even if it has been previously submitted with the same options. This may result in additional charges." }, "prevent_c2pa_forces": { "type": "boolean", "description": "If true, C2PA signature does not force the origin to artificial. If false or undefined, C2PA signature will force the origin to artificial (current behaviour)." }, "with_nsfw": { "type": "boolean", "description": "Set it to true if you also want to enable NSFW (Not Safe For Work) content detection." } }, "required": [ "image" ] }, "encoding": { "image": { "contentType": "image/png, image/jpeg, image/jpg, image/webp, image/tiff" } } } } }, "responses": { "200": { "description": "The classification identifier. The format depends on the Accept header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "example": { "identifier": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } }, "text/plain": { "schema": { "type": "string", "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" }, "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "400": { "description": "The user has no enough credits to perform the operation, the request contains the wrong parameters or the media did not pass validation steps.", "content": { "application/json": { "examples": { "missing_image": { "value": { "error": { "image": [ "The image field is required" ] } } }, "invalid_image_format": { "value": { "error": { "image": [ "The image must be a file of type: png, jpeg, jpg, webp, tiff." ] } } }, "image_too_large": { "value": { "error": { "image": [ "The image may not be greater than 50Mb." ] } } } } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/image_fromurl": { "post": { "summary": "Classify an image from URL", "description": "Submit an image to be classified as human or artificial.\n\nšŸ” Response format varies based on the `Accept` header:\n\n`Accept: application/json` ā†’ `{ \"identifier\": \"...\" }`\n\n Other values (e.g. `text/plain`) ā†’ plain text with just the identifier string.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Accept", "in": "header", "description": "Response content type. Supported: application/json, text/plain.", "required": false, "schema": { "type": "string", "enum": [ "application/json", "text/plain" ] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file_url": { "type": "string", "description": "The URL of the image to be classified." }, "ref_id": { "type": "string", "description": "An optional reference ID to associate with the classification request." }, "with_morphing": { "type": "boolean", "description": "Set it to true if you also want to analyze people's faces in the image using morphing." }, "with_tampering": { "type": "boolean", "description": "Set it to true if you also want to analyze signs of tampering or manipulation without the aid of a Generative AI" }, "with_heatmap": { "type": "boolean", "description": "Set it to true if you also want to get an AI content heatmap." }, "webhook_url": { "type": "string", "description": "If specified, the classification result will also be automatically sent to the entered URL. Otherwise, the result can be obtained by polling the [relative endpoint](./get-classification-result). Please note that in order to use a webhook callback URL **you need to request a specific enablement**, otherwise the parameter is ignored. Moreover, the system may cache the analysis results of repeated submissions, i.e. submissions of the same file with the same options: in this case the webhook won't be called and the results would be accessible only by polling the [relative endpoint](./get-classification-result)." }, "no_cache": { "type": "boolean", "description": "Set it to true to force the system to reprocess the image even if it has been previously submitted with the same options. This may result in additional charges." }, "prevent_c2pa_forces": { "type": "boolean", "description": "If true, C2PA signature does not force the origin to artificial. If false or undefined, C2PA signature will force the origin to artificial (current behaviour)." }, "with_nsfw": { "type": "boolean", "description": "Set it to true if you also want to enable NSFW (Not Safe For Work) content detection." } }, "required": [ "file_url" ] } } } }, "responses": { "200": { "description": "The classification identifier. The format depends on the Accept header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "example": { "identifier": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } }, "text/plain": { "schema": { "type": "string", "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" }, "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "400": { "description": "The user has no enough credits to perform the operation, the request contains the wrong parameters, the URL validation has failed or the download failed or the file type is not supported.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Validation Error Example", "value": { "error": "The file_url field is required." } }, "unsupported_format": { "summary": "Unsupported File Format", "value": { "error": "The uploaded file format is not supported." } }, "file_too_large": { "summary": "File Too Large", "value": { "error": "The uploaded file exceeds the maximum allowed size of 50Mb." } } } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/classification/{identifier}": { "get": { "summary": "Get single image classification result", "description": "Retrieve the classification result for a specific image.\n\n**Note:** This endpoint also has an alias available at `/api/classification_image/{identifier}`.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier of the image." } ], "responses": { "200": { "description": "The classification result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/classification/{hash}/override": { "post": { "summary": "Override image classification", "description": "Submit an override for an image classification. The hash parameter uniquely identifies the submitted image file. If the same image (so the same hash) is uploaded multiple times, the override will be applied to all submissions that share this hash.\n\n**Note:** This endpoint also has an alias available at `/api/classification_image/{hash}/override`.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The hash of the image." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "human", "artificial" ], "description": "The correct classification." } }, "required": [ "classification" ] } } } }, "responses": { "201": { "description": "Report created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "human", "artificial" ], "description": "The reported classification." }, "type": { "type": "string", "enum": [ "image" ], "description": "The type of content." }, "hash": { "type": "string", "description": "The hash of the image." } }, "required": [ "classification", "type", "hash" ] }, "example": { "classification": "human", "type": "image", "hash": "862bb7de43b131a38b64753269d643443a21069a04ab66a56c9818956f590cb9" } } } }, "400": { "description": "Override already submitted, no request associated with this hash, content not classified yet, override no longer accepted, or validation errors.", "content": { "application/json": { "examples": { "validation_required": { "summary": "Classification field required", "value": { "classification": [ "The classification field is required." ] } }, "validation_invalid": { "summary": "Invalid classification value", "value": { "classification": [ "The selected classification is invalid." ] } }, "no_request": { "summary": "No request associated with this hash", "value": { "error": "You haven't got any request for this content." } }, "already_submitted": { "summary": "Override already submitted", "value": { "error": "You have already submitted a report for this content." } }, "not_classified": { "summary": "Content not classified yet", "value": { "error": "This image was not classified yet." } }, "no_longer_possible": { "summary": "Override no longer accepted", "value": { "error": "Is no longer possible to send a report for this image." } } } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/classification/heatmap/{identifier}": { "get": { "summary": "Get an image AI heatmap", "description": "Retrieve the AI heatmap for a specific image.\n\n**Note:** This endpoint also has an alias available at `/api/classification_image/heatmap/{identifier}`.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier of the image." } ], "responses": { "200": { "description": "The image AI heatmap.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "204": { "description": "The specified image does not have an associated heatmap. This response has no body data.", "content": { "application/json": { "example": { "error": "The specified image does not have an associated heatmap. This response has no body data." } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/classification_video": { "post": { "summary": "Classify a video", "description": "Submit a video for classification\n\nšŸ” Response format varies based on the `Accept` header:\n\n`Accept: application/json` ā†’ `{ \"identifier\": \"...\" }`\n\n Other values (e.g. `text/plain`) ā†’ plain text with just the identifier string.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Accept", "in": "header", "description": "Response content type. Supported: application/json, text/plain.", "required": false, "schema": { "type": "string", "enum": [ "application/json", "text/plain" ] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "video": { "type": "string", "format": "binary", "description": "The video to be classified. **Supported formats:** Any video format (MP4, AVI, MOV, etc.). **MIME types:** Any mimetype starting with 'video/' (e.g., video/mp4, video/avi, video/quicktime). **Maximum file size:** 50MB." }, "ref_id": { "type": "string", "description": "An optional reference ID to associate with the classification request." }, "frames": { "type": "integer", "enum": [ 5, 10, 30 ], "description": "Choose to classify a maximum of 5, 10 or 30 frames." }, "key_frames": { "type": "boolean", "description": "If set to true extracts key frames and uses those for classification instead of fixed-time distance images. The extracted key frames may be less than the requested `frames`." }, "key_frames_method": { "type": "string", "enum": [ "iframes", "flow", "color" ], "description": "Key frames identification algorithm. Possible values are **iframes** (default), **flow** and **color**.\n - `iframes` : extracts the iframes of the video; \n - `color` : returns the average frame, based on color, of every shot sequence. *Shot sequences* are group of frames that start with an iframe; \n - `flow` : returns the most still frame with respect of the previous frame of every shot sequence." }, "with_tampering": { "type": "boolean", "description": "Set it to true if you also want to analyze the image for signs of tampering or manipulation, without the aid of a Generative AI." }, "with_morphing": { "type": "boolean", "description": "Set it to true if you also want to analyze people's faces in the image using morphing." }, "with_audio": { "type": "boolean", "description": "**[BETA]** Set it to true if you also want to analyze the audio track of the video. **You must be enabled in your pricing plan** to use this option." }, "webhook_url": { "type": "string", "description": "If specified, the classification result will also be automatically sent to the entered URL. Otherwise, the result can be obtained by polling the [relative endpoint](./get-classification-result-video). Please note that in order to use a webhook callback URL **you need to request a specific enablement**, otherwise the parameter is ignored. Moreover, the system may cache the analysis results of repeated submissions, i.e. submissions of the same file with the same options: in this case the webhook won't be called and the results would be accessible only by polling the [relative endpoint](./get-classification-result-video)." }, "no_cache": { "type": "boolean", "description": "Set it to true to force the system to reprocess the image even if it has been previously submitted with the same options. This may result in additional charges." }, "prevent_c2pa_forces": { "type": "boolean", "description": "If true, C2PA signature does not force the origin to artificial. If false or undefined, C2PA signature will force the origin to artificial (current behaviour)." }, "with_nsfw": { "type": "boolean", "description": "Set it to true if you also want to enable NSFW (Not Safe For Work) content detection." }, "ensure_face_per_frame": { "type": "boolean", "description": "Set it to true to ensure that at least a face is detected in each frame used for classification. Use it in combination with `with_morphing` option to detect potential face swaps or morphing occurring in the video. This option **may increase processing** time." } }, "required": [ "video" ] }, "encoding": { "video": { "contentType": "video/*" } } } } }, "responses": { "200": { "description": "The classification identifier. The format depends on the Accept header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "example": { "identifier": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } }, "text/plain": { "schema": { "type": "string", "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" }, "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "400": { "description": "The user has no enough credits to perform the operation, the request contains the wrong parameters or the media did not pass validation steps.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Validation Error Example", "value": { "video": [ "The video field is required." ] } }, "unsupported_format": { "summary": "Unsupported File Format", "value": { "error": "The uploaded file format is not supported." } }, "file_too_large": { "summary": "File Too Large", "value": { "error": "The uploaded file exceeds the maximum allowed size of 5GB." } } } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/video_fromurl": { "post": { "summary": "Classify a video from URL", "description": "Submit a video for classification\n\nšŸ” Response format varies based on the `Accept` header:\n\n`Accept: application/json` ā†’ `{ \"identifier\": \"...\" }`\n\n Other values (e.g. `text/plain`) ā†’ plain text with just the identifier string.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Accept", "in": "header", "description": "Response content type. Supported: application/json, text/plain.", "required": false, "schema": { "type": "string", "enum": [ "application/json", "text/plain" ] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file_url": { "type": "string", "description": "The URL of the video to be classified." }, "ref_id": { "type": "string", "description": "An optional reference ID to associate with the classification request." }, "frames": { "type": "integer", "enum": [ 5, 10, 30 ], "description": "Choose to classify a maximum of 5, 10 or 30 frames." }, "key_frames": { "type": "boolean", "description": "If set to true extracts key frames and uses those for classification instead of fixed-time distance images. The extracted key frames may be less than the requested `frames`." }, "key_frames_method": { "type": "string", "enum": [ "iframes", "flow", "color" ], "description": "Key frames identification algorithm. Possible values are **iframes** (default), **flow** and **color**.\n - `iframes` : extracts the iframes of the video; \n - `color` : returns the average frame, based on color, of every shot sequence. *Shot sequences* are group of frames that start with an iframe; \n - `flow` : returns the most still frame with respect of the previous frame of every shot sequence." }, "with_tampering": { "type": "boolean", "description": "Set it to true if you also want to analyze the image for signs of tampering or manipulation, without the aid of a Generative AI." }, "with_morphing": { "type": "boolean", "description": "Set it to true if you also want to analyze people's faces in the image using morphing." }, "with_audio": { "type": "boolean", "description": "**[BETA]** Set it to true if you also want to analyze the audio track of the video. **You must be enabled in your pricing plan** to use this option." }, "webhook_url": { "type": "string", "description": "If specified, the classification result will also be automatically sent to the entered URL. Otherwise, the result can be obtained by polling the [relative endpoint](./get-classification-result-video). Please note that in order to use a webhook callback URL **you need to request a specific enablement**, otherwise the parameter is ignored. Moreover, the system may cache the analysis results of repeated submissions, i.e. submissions of the same file with the same options: in this case the webhook won't be called and the results would be accessible only by polling the [relative endpoint](./get-classification-result-video)." }, "no_cache": { "type": "boolean", "description": "Set it to true to force the system to reprocess the image even if it has been previously submitted with the same options. This may result in additional charges." }, "prevent_c2pa_forces": { "type": "boolean", "description": "If true, C2PA signature does not force the origin to artificial. If false or undefined, C2PA signature will force the origin to artificial (current behaviour)." }, "with_nsfw": { "type": "boolean", "description": "Set it to true if you also want to enable NSFW (Not Safe For Work) content detection." }, "ensure_face_per_frame": { "type": "boolean", "description": "Set it to true to ensure that at least a face is detected in each frame used for classification. Use it in combination with `with_morphing` option to detect potential face swaps or morphing occurring in the video. This option **may increase processing** time." } }, "required": [ "file_url" ] } } } }, "responses": { "200": { "description": "The classification identifier. The format depends on the Accept header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "example": { "identifier": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } }, "text/plain": { "schema": { "type": "string", "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" }, "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "400": { "description": "The user has no enough credits to perform the operation, the URL validation has failed, the download failed or the file type is not supported.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Validation Error Example", "value": { "file_url": "The file_url field is required." } }, "unsupported_format": { "summary": "Unsupported File Format", "value": { "error": "The uploaded file format is not supported." } }, "file_too_large": { "summary": "File Too Large", "value": { "error": "The file exceeds the maximum allowed size of 5GB." } } } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } } } } }, "/api/classification_video/{identifier}": { "get": { "summary": "Get single video classification result", "description": "Retrieve the classification result for a specific video.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier of the video." } ], "responses": { "200": { "description": "The classification result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoResponse" } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The specified identifier does not exist or is not accessible by the user.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/classification_video/{hash}/override": { "post": { "summary": "Override video classification", "description": "Submit an override for a video classification. The hash parameter uniquely identifies the submitted video file. If the same video (so the same hash) is uploaded multiple times, the override will be applied to all submissions that share this hash.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The hash of the video." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "human", "artificial" ], "description": "The correct classification." } }, "required": [ "classification" ] } } } }, "responses": { "201": { "description": "Override created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "human", "artificial" ], "description": "The override classification." }, "type": { "type": "string", "enum": [ "video" ], "description": "The type of content." }, "hash": { "type": "string", "description": "The hash of the video." } }, "required": [ "classification", "type", "hash" ] }, "example": { "classification": "artificial", "type": "video", "hash": "1122bc922b7381529013a2198b9143c0b6a52669fd511cfb030418209f1751a6" } } } }, "400": { "description": "Override already submitted, no request associated with this hash, content not classified yet, override no longer accepted, no completed request for this video, or validation errors.", "content": { "application/json": { "examples": { "validation_required": { "summary": "Classification field required", "value": { "classification": [ "The classification field is required." ] } }, "validation_invalid": { "summary": "Invalid classification value", "value": { "classification": [ "The selected classification is invalid." ] } }, "no_request": { "summary": "No request associated with this hash", "value": { "error": "You haven't got any request for this content." } }, "already_submitted": { "summary": "Override already submitted", "value": { "error": "You have already submitted a report for this content." } }, "not_classified": { "summary": "Content not classified yet", "value": { "error": "This video was not classified yet." } }, "no_longer_possible": { "summary": "Override no longer accepted", "value": { "error": "Is no longer possible to send a report for this video." } }, "no_completed_request": { "summary": "No completed request for this video", "value": { "error": "No completed request for this video exists." } } } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/classification_audio": { "post": { "summary": "Classify a speech", "description": "Submit a speech for classification\n\nšŸ” Response format varies based on the `Accept` header:\n\n`Accept: application/json` ā†’ `{ \"identifier\": \"...\" }`\n\n Other values (e.g. `text/plain`) ā†’ plain text with just the identifier string.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Accept", "in": "header", "description": "Response content type. Supported: application/json, text/plain.", "required": false, "schema": { "type": "string", "enum": [ "application/json", "text/plain" ] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "audio": { "type": "string", "format": "binary", "description": "The speech to be classified. **Supported formats:** MP3, WAV, OGG, FLAC, AAC, 3GP, M4A, M4B, M4P, M4R, MP4. **MIME types:** audio/mpeg, audio/wav, audio/ogg, audio/flac, audio/aac, audio/3gp, audio/m4a, audio/m4b, audio/m4p, audio/m4r, video/mp4. **Maximum file size:** 15MB." }, "ref_id": { "type": "string", "description": "An optional reference ID to associate with the classification request." }, "webhook_url": { "type": "string", "description": "If specified, the classification result will also be automatically sent to the entered URL. Otherwise, the result can be obtained by polling the [relative endpoint](./get-classification-result-speech). Please note that in order to use a webhook callback URL **you need to request a specific enablement**, otherwise the parameter is ignored. Moreover, the system may cache the analysis results of repeated submissions, i.e. submissions of the same file with the same options: in this case the webhook won't be called and the results would be accessible only by polling the [relative endpoint](./get-classification-result-speech)." }, "no_cache": { "type": "boolean", "description": "Set it to true to force the system to reprocess the image even if it has been previously submitted with the same options. This may result in additional charges." }, "prevent_c2pa_forces": { "type": "boolean", "description": "If true, C2PA signature does not force the origin to artificial. If false or undefined, C2PA signature will force the origin to artificial (current behaviour)." } }, "required": [ "audio" ] }, "encoding": { "audio": { "contentType": "audio/mpeg, audio/wav, audio/ogg, audio/flac, audio/aac, audio/3gp, audio/m4a, audio/m4b, audio/m4p, audio/m4r, video/mp4" } } } } }, "responses": { "200": { "description": "The classification identifier. The format depends on the Accept header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "example": { "identifier": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } }, "text/plain": { "schema": { "type": "string" }, "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "400": { "description": "The user has no enough credits to perform the operation, the request contains the wrong parameters or the media did not pass validation steps.", "content": { "application/json": { "examples": { "missing_audio": { "summary": "Validation Error Example", "value": { "audio": [ "The audio field is required." ] } }, "unsupported_format": { "summary": "Unsupported File Format", "value": { "error": "The uploaded file format is not supported." } }, "file_too_large": { "summary": "File Too Large", "value": { "error": "The uploaded file exceeds the maximum allowed size of 50MB." } } } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/audio_fromurl": { "post": { "summary": "Classify a speech from URL", "description": "Submit a speech for classification\n\nšŸ” Response format varies based on the `Accept` header:\n\n`Accept: application/json` ā†’ `{ \"identifier\": \"...\" }`\n\n Other values (e.g. `text/plain`) ā†’ plain text with just the identifier string.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Accept", "in": "header", "description": "Response content type. Supported: application/json, text/plain.", "required": false, "schema": { "type": "string", "enum": [ "application/json", "text/plain" ] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file_url": { "type": "string", "description": "The URL of the speech to be classified." }, "ref_id": { "type": "string", "description": "An optional reference ID to associate with the classification request." }, "webhook_url": { "type": "string", "description": "If specified, the classification result will also be automatically sent to the entered URL. Otherwise, the result can be obtained by polling the [relative endpoint](./get-classification-result-speech). Please note that in order to use a webhook callback URL **you need to request a specific enablement**, otherwise the parameter is ignored. Moreover, the system may cache the analysis results of repeated submissions, i.e. submissions of the same file with the same options: in this case the webhook won't be called and the results would be accessible only by polling the [relative endpoint](./get-classification-result-speech)." }, "no_cache": { "type": "boolean", "description": "Set it to true to force the system to reprocess the image even if it has been previously submitted with the same options. This may result in additional charges." } }, "required": [ "file_url" ] } } } }, "responses": { "200": { "description": "The classification identifier. The format depends on the Accept header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "example": { "identifier": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } }, "text/plain": { "schema": { "type": "string", "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" }, "example": "8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0" } } }, "400": { "description": "The user has no enough credits to perform the operation, the request contains the wrong parameters or the media did not pass validation steps.", "content": { "application/json": { "examples": { "missing_file_url": { "summary": "Validation Error Example", "value": { "file_url": "The file_url field is required." } }, "invalid_url": { "summary": "Invalid URL", "value": { "error": "The provided file_url is not a valid URL." } }, "unsupported_format": { "summary": "Unsupported File Format", "value": { "error": "The file format at the provided URL is not supported." } }, "file_too_large": { "summary": "File Too Large", "value": { "error": "The file at the provided URL exceeds the maximum allowed size of 50MB." } } } } } }, "401": { "description": "Unknown or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/classification_audio/{identifier}": { "get": { "summary": "Get single audio classification result", "description": "Retrieve the classification result for a specific audio.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier of the audio file." } ], "responses": { "200": { "description": "The classification result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioResponse" } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The specified identifier does not exist or is not accessible by the user.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/classification_audio/{hash}/override": { "post": { "summary": "Override audio classification", "description": "Submit an override for an audio classification. The hash parameter uniquely identifies the submitted audio file. If the same audio (so the same hash) is uploaded multiple times, the override will be applied to all submissions that share this hash.", "tags": [ "Classification" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The hash of the audio." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "human", "artificial" ], "description": "The correct classification." } }, "required": [ "classification" ] } } } }, "responses": { "201": { "description": "Override created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "human", "artificial" ], "description": "The override classification." }, "type": { "type": "string", "enum": [ "audio" ], "description": "The type of content." }, "hash": { "type": "string", "description": "The hash of the audio." } }, "required": [ "classification", "type", "hash" ] }, "example": { "classification": "human", "type": "audio", "hash": "89ff6bc9ec8ed4b9fe5489353432b1553ac8efe5e26f247f71d75e0da181870f" } } } }, "400": { "description": "The user has no enough credits to perform the operation, the request contains the wrong parameters or the media did not pass validation steps.", "content": { "application/json": { "examples": { "validation_required": { "summary": "Classification field required", "value": { "classification": [ "The classification field is required." ] } }, "validation_invalid": { "summary": "Invalid classification value", "value": { "classification": [ "The selected classification is invalid." ] } }, "no_request": { "summary": "No request associated with this hash", "value": { "error": "You haven't got any request for this content." } }, "already_submitted": { "summary": "Override already submitted", "value": { "error": "You have already submitted a report for this content." } }, "not_classified": { "summary": "Content not classified yet", "value": { "error": "This audio was not classified yet." } }, "no_longer_possible": { "summary": "Override no longer accepted", "value": { "error": "Is no longer possible to send a report for this audio." } } } } } }, "401": { "description": "Invalid or missing API key.", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "403": { "description": "The user is not authorized to access this API or did not accept the terms of service.", "content": { "application/json": { "example": { "error": "Forbidden" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/health": { "get": { "summary": "Check infrastructure health", "description": "This API is useful to check the infrastructure status. It does not require authentication and it is not rate limited.\n\nThe response includes a `status` field with one of these values:\n- `ok`: all monitored infrastructure components are fully operational.\n- `degraded`: the service is reachable, but one or more components are operating with reduced functionality.", "tags": [ "Infrastructure" ], "security": [ {} ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request GET \\\n --url https://backend.identifai.net/api/health" } ], "responses": { "200": { "description": "The infrastructure is up and operative.", "content": { "application/json": { "example": { "status": [ "ok", "degraded" ] } } } } } } }, "/api/partner/user": { "post": { "summary": "Create or update user", "description": "Creates a new user or updates an existing one. Partners can only create or update users under their partnership.", "tags": [ "Partner" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "The ID of the user (required only for updates, `null` for creation)." }, "name": { "type": "string", "description": "The full name of the user." }, "email": { "type": "string", "format": "email", "description": "The email address of the user." }, "password": { "type": "string", "format": "password", "description": "The password for the user." }, "heuristic": { "type": "string", "description": "The euristic assigned to the user." }, "pricing_id": { "type": "integer", "description": "The pricing tier ID for the user." }, "readonly": { "type": "boolean", "description": "Indicates whether the user has read-only permissions." }, "newsletter": { "type": "boolean", "description": "True if the user has opted in for the newsletter." }, "save_files": { "type": "boolean", "description": "True if the user can store submitted files." } }, "required": [ "id", "name", "email", "heuristic", "pricing_id" ] } } } }, "responses": { "200": { "description": "Created or updated user", "content": { "application/json": { "example": { "data": { "id": 233, "name": "UserName", "email": "UserName@mail.com", "email_verified_at": "2025-03-12T11:30:25.000000Z", "address": null, "zip": null, "city": null, "country": null, "phone": null, "contact": null, "vat": null, "created_at": "2025-03-12T11:30:25.000000Z", "updated_at": "2025-03-12T11:30:25.000000Z", "balance": null, "heuristic": "AverageExcludeObsolete", "readonly": null, "pricing": { "id": 1, "name": "TestB", "sku": "testB" }, "partner": { "id": 221, "name": "PartnerName", "email": "PartnerName@mail.com", "email_verified_at": "2025-03-03T11:22:49.000000Z", "address": null, "zip": null, "city": null, "country": null, "phone": null, "contact": null, "vat": null, "created_at": "2025-03-03T11:22:49.000000Z", "updated_at": "2025-03-03T13:27:06.000000Z", "balance": 0, "heuristic": "Average", "readonly": false, "pricing": { "id": 2, "name": "TestAC", "sku": "testAC" }, "partner": null } } }, "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Invalid or missing API key" }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } }, "delete": { "summary": "Delete user", "description": "Delete a user profile", "tags": [ "User" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "OK" }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/user/credits": { "get": { "summary": "Get user credits", "description": "Get user credits", "tags": [ "User" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "An object containing the user credits", "content": { "application/json": { "example": { "available_credits": 159, "total_spent": 41 }, "schema": { "$ref": "#/components/schemas/Credits" } } } }, "401": { "description": "Invalid or missing API key" }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/partner/users": { "get": { "summary": "Retrieve users", "description": "Fetches a list of users based on the specified filters.", "tags": [ "Partner" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter users by name or email (partial match)." }, { "name": "pricing_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter users by their pricing tier ID." }, { "name": "order", "in": "query", "schema": { "type": "string", "default": "id" }, "description": "Specify the field to sort results by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "desc", "asc" ] }, "description": "Sorting direction: `asc` for ascending, `desc` for descending." }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page. If omitted, all results are returned." } ], "responses": { "200": { "description": "A paginated list of users matching the search criteria.", "content": { "application/json": { "example": { "current_page": 1, "data": [ { "id": 222, "name": "User", "email": "User@mail.com", "email_verified_at": "2025-03-03T13:28:03.000000Z", "address": null, "zip": null, "city": null, "country": null, "phone": null, "contact": null, "vat": null, "created_at": "2025-03-03T13:28:03.000000Z", "updated_at": "2025-03-12T09:32:43.000000Z", "balance": 0, "heuristic": "AverageExcludeObsolete", "readonly": null, "pricing": { "id": 1, "name": "TestB", "sku": "testB" }, "partner": { "id": 221, "name": "Partner", "email": "Partner@gmail.com", "email_verified_at": "2025-03-03T11:22:49.000000Z", "address": null, "zip": null, "city": null, "country": null, "phone": null, "contact": null, "vat": null, "created_at": "2025-03-03T11:22:49.000000Z", "updated_at": "2025-03-03T13:27:06.000000Z", "balance": 0, "heuristic": "Average", "readonly": false, "pricing": { "id": 2, "name": "TestAC", "sku": "testAC" }, "partner": null } } ], "from": 1, "last_page": 1, "next_page_url": null, "per_page": 100, "to": 1, "total": 1 }, "schema": { "$ref": "#/components/schemas/UserList" } } } }, "400": { "description": "Invalid query parameters, missing pricing or not accessible, no more seats available for partner pricing, or incorrect password." }, "403": { "description": "Parner not authorized to access the user or the user is not authorized to use the API." }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/partner/send_creation_email": { "post": { "summary": "Send creation email", "description": "Sends an email to the specified user containing a password reset link or account activation instructions.", "tags": [ "Partner" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The id of the user for whom the email should be sent." } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Email successfully sent to the specified user.", "content": { "application/json": { "example": { "data": { "id": 222, "name": "User", "email": "user@mail.com", "email_verified_at": "2025-03-03T13:28:03.000000Z", "address": null, "zip": null, "city": null, "country": null, "phone": null, "contact": null, "vat": null, "created_at": "2025-03-03T13:28:03.000000Z", "updated_at": "2025-03-12T09:32:43.000000Z", "balance": 0, "heuristic": "AverageExcludeObsolete", "readonly": null, "pricing": { "id": 1, "name": "TestB", "sku": "testB" }, "partner": { "id": 221, "name": "Partner", "email": "partner@gmail.com", "email_verified_at": "2025-03-03T11:22:49.000000Z", "address": null, "zip": null, "city": null, "country": null, "phone": null, "contact": null, "vat": null, "created_at": "2025-03-03T11:22:49.000000Z", "updated_at": "2025-03-03T13:27:06.000000Z", "balance": 0, "heuristic": "Average", "readonly": false, "pricing": { "id": 2, "name": "TestAC", "sku": "testAC" }, "partner": null } } }, "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Input validation failed." }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "User not found." }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } }, "/api/partner/pricings": { "get": { "summary": "Get pricings", "description": "Fetch the list of available pricing plans.", "tags": [ "Partner" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "order", "in": "query", "schema": { "type": "string", "default": "created_at" }, "description": "Specify the field to sort results by." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" }, "description": "Sorting direction: `asc` for ascending, `desc` for descending." }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page. If omitted, all results are returned." } ], "responses": { "200": { "description": "Successful response containing a paginated list of available pricing plans.", "content": { "application/json": { "example": { "current_page": 1, "data": [ { "id": 2, "name": "TestAC", "sku": "testAC" }, { "id": 1, "name": "TestB", "sku": "testB" } ], "from": 1, "last_page": 1, "next_page_url": null, "per_page": 10, "to": 2, "total": 2 }, "schema": { "$ref": "#/components/schemas/PricingList" } } } }, "401": { "description": "Invalid or missing API key" }, "429": { "description": "Too many requests.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } } } }, "components": { "schemas": { "Status": { "type": "string", "enum": [ "new", "done", "errored" ] }, "ImageResponse": { "type": "object", "description": "The answer for image classification", "properties": { "hash": { "type": "string", "description": "SHA-256 hash of the classified image file" }, "identifier": { "type": "string", "description": "The identifier that identifies the classified image" }, "api_version": { "type": "string", "nullable": true, "description": "The API version at the time of the analysis (available from **v1.1.0**). The value is set when the analysis completes." }, "status": { "$ref": "#/components/schemas/Status", "description": "The processing status of the classification request (available from **v1.1.0**)" }, "errors": { "type": "string", "nullable": true, "description": "Error messages if the status is 'errored' (available from **v1.1.0**)" }, "name": { "type": "string", "description": "The name of the classified image file" }, "ref_id": { "type": "string", "description": "An optional reference ID to associate with the classification request." }, "result_url": { "type": "string", "format": "uri", "description": "URL where the classification results can be found on the dashboard" }, "is_nsfw": { "type": "boolean", "nullable": true, "description": "Indicates if NSFW (Not Safe For Work) content was detected. Only present if with_nsfw was set to true in the classification request." }, "c2pa": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/C2PA" } ], "description": "Coalition for Content Provenance and Authenticity information that certifies the source and history of media content. Contains manifests, validation results, and signature information. Null if the image doesn't contain C2PA metadata." }, "has_heatmap": { "type": "boolean", "description": "If the image has an AI content heatmap. The heatmap png can be retrieved from the specific endpoint `/api/classification/heatmap/{identifier}`." }, "verdict": { "$ref": "#/components/schemas/Verdict", "description": "The main classification verdict using the user's default heuristic" }, "verdicts": { "type": "array", "items": { "$ref": "#/components/schemas/Verdict" }, "description": "Array of verdicts for all available heuristics" }, "force_classification": { "type": "string", "enum": [ "human", "artificial" ], "nullable": true, "description": "If present, indicates that the user has forced the classification to the specified value" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Result" }, "description": "Detailed classification results from each AI detection model" }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectDetails" }, "description": "Details about object detection inside the image" } } }, "AudioResponse": { "type": "object", "description": "The answer for audio classification", "properties": { "hash": { "type": "string", "description": "SHA-256 hash of the classified audio file" }, "identifier": { "type": "string", "description": "The identifier that identifies the classified audio" }, "api_version": { "type": "string", "nullable": true, "description": "The API version at the time of the analysis (available from **v1.1.0**). The value is set when the analysis completes." }, "status": { "$ref": "#/components/schemas/Status", "description": "The processing status of the classification request (available from **v1.1.0**)" }, "errors": { "type": "string", "nullable": true, "description": "Error messages if the status is 'errored' (available from **v1.1.0**)" }, "name": { "type": "string", "description": "The name of the classified audio file" }, "ref_id": { "type": "string", "description": "An optional reference ID to associate with the classification request." }, "result_url": { "type": "string", "format": "uri", "description": "URL where the classification results can be found on the dashboard" }, "verdict": { "$ref": "#/components/schemas/Verdict", "description": "The main classification verdict using the user's default heuristic" }, "verdicts": { "type": "array", "items": { "$ref": "#/components/schemas/Verdict" }, "description": "Array of verdicts for all available heuristics" }, "force_classification": { "type": "string", "enum": [ "human", "artificial" ], "nullable": true, "description": "If present, indicates that the user has forced the classification to the specified value" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Result" }, "description": "Detailed classification results from each AI detection model" }, "details": { "$ref": "#/components/schemas/MediaDetails", "description": "Per-segment details of the audio analysis, with each entry representing a clip extracted from the submitted audio" } } }, "VideoResponse": { "type": "object", "description": "The answer for video classification", "properties": { "hash": { "type": "string", "description": "SHA-256 hash of the classified video file" }, "identifier": { "type": "string", "description": "The identifier that identifies the classified video" }, "api_version": { "type": "string", "nullable": true, "description": "The API version at the time of the analysis (available from **v1.1.0**). The value is set when the analysis completes." }, "status": { "$ref": "#/components/schemas/Status", "description": "The processing status of the classification request (available from **v1.1.0**)" }, "errors": { "type": "string", "nullable": true, "description": "Error messages if the status is 'errored' (available from **v1.1.0**)" }, "name": { "type": "string", "description": "The name of the classified video file" }, "ref_id": { "type": "string", "description": "An optional reference ID to associate with the classification request." }, "result_url": { "type": "string", "format": "uri", "description": "URL where the classification results can be found on the dashboard" }, "is_nsfw": { "type": "boolean", "nullable": true, "description": "Indicates if NSFW (Not Safe For Work) content was detected. Only present if with_nsfw was set to true in the classification request." }, "verdict": { "$ref": "#/components/schemas/VideoVerdict", "description": "The main classification verdict for the entire video using the user's default heuristic" }, "verdicts": { "type": "array", "items": { "$ref": "#/components/schemas/VideoVerdict" }, "description": "Array of verdicts for all available heuristics applied to the entire video" }, "force_classification": { "type": "string", "enum": [ "human", "artificial" ], "nullable": true, "description": "If present, indicates that the user has forced the classification to the specified value" }, "results": { "type": "object", "description": "Detailed results containing analyzed frames from the video", "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/ImageResponse" }, "description": "Array of image classification results for each extracted frame from the video. Each frame is analyzed as an independent image." }, "audios": { "type": "array", "items": { "$ref": "#/components/schemas/AudioResponse" }, "description": "Array of audio classification results if audio analysis was requested" } } } } }, "VideoVerdict": { "type": "object", "description": "The final classification verdict for a video, aggregating results across all analyzed frames", "properties": { "count": { "type": "integer", "description": "Number of frames analyzed in the video" }, "models": { "type": "array", "items": { "type": "string", "description": "Model name" }, "description": "Array of models used for analysis (may be omitted if all models are used)" }, "unknown": { "type": "boolean", "description": "Indicates if the video contains frames that couldn't be confidently classified" }, "heuristic": { "type": "string", "description": "Name of the heuristic used (e.g., 'Majority', 'Average', 'AverageExcludeObsolete', 'TopRelevant')" }, "confidence": { "type": "number", "description": "The confidence of the classification result from 0 to 1, aggregated across all frames" }, "classification": { "type": "string", "enum": [ "human", "artificial" ], "description": "The final classification result for the entire video using the specified heuristic" } }, "required": [ "heuristic", "confidence", "classification" ] }, "Verdict": { "type": "object", "description": "The final classification response for the considered heuristic", "properties": { "models": { "type": "array", "items": { "type": "string", "description": "Model name" }, "description": "Array of models used" }, "heuristic": { "type": "string", "description": "Name of the heuristic used (e.g., 'Majority', 'Average', 'AverageExcludeObsolete', 'TopRelevant')" }, "confidence": { "type": "number", "description": "The confidence of the classification result from 0 to 1" }, "classification": { "type": "string", "enum": [ "human", "artificial" ], "description": "The final classification result using the specified heuristic" } }, "required": [ "heuristic", "confidence", "classification" ] }, "Result": { "type": "object", "description": "The score obtained in each category (human or artificial) for the model used", "properties": { "model": { "type": "string", "description": "The name of the AI detection model used for classification" }, "unknown": { "type": "boolean", "description": "Indicates if the model couldn't confidently classify the image (uncertainty detected)" }, "elapsed_time": { "type": "number", "description": "The time taken for classification in seconds" }, "classification": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Category", "enum": [ "human", "artificial" ] }, "score": { "type": "number", "description": "Score from 0 to 1" } } }, "description": "Array of classification scores for each category" }, "classification_details": { "type": "object", "description": "Additional details about the classification process" } } }, "ObjectDetails": { "type": "object", "properties": { "detections": { "type": "array", "items": { "type": "object", "properties": { "box": { "type": "object", "properties": { "x1": { "type": "number" }, "x2": { "type": "number" }, "y1": { "type": "number" }, "y2": { "type": "number" } }, "required": [ "x1", "x2", "y1", "y2" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "unknown": { "type": "boolean" }, "elapsed_time": { "type": "number" }, "classification": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "score": { "type": "number" } }, "required": [ "label", "score" ] } }, "classification_details": { "type": "object", "properties": { "confidence": { "type": "number" } }, "required": [ "confidence" ] } }, "required": [ "model", "unknown", "elapsed_time", "classification", "classification_details" ] } }, "verdict": { "type": "object", "properties": { "heuristic": { "type": "string" }, "confidence": { "type": "number" }, "classification": { "type": "string" } }, "required": [ "heuristic", "confidence", "classification" ] } }, "required": [ "box", "results", "verdict" ] } } }, "required": [ "detections" ] }, "MediaDetails": { "type": "object", "description": "Container for per-segment analysis details", "properties": { "clips": { "type": "array", "items": { "$ref": "#/components/schemas/ClipDetail" }, "description": "Array of analysis results for each segment (clip) extracted from the submitted media file" } }, "required": [ "clips" ] }, "ClipDetail": { "type": "object", "description": "Detailed information about a specific clip (audio or video segment) analysis", "properties": { "index": { "type": "integer", "description": "The index of the clip in the sequence" }, "start": { "type": "number", "description": "Start time of the clip in seconds" }, "end": { "type": "number", "description": "End time of the clip in seconds" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Result" }, "description": "Detailed classification results from each AI detection model for this clip" }, "verdict": { "$ref": "#/components/schemas/Verdict", "description": "The classification verdict for this specific clip" } }, "required": [ "index", "start", "end", "results", "verdict" ] }, "Credits": { "type": "object", "properties": { "total_spent": { "type": "number", "description": "Credits used so far" }, "available_credits": { "type": "number", "description": "Available credits" } } }, "Pricing": { "type": "object", "properties": { "id": { "type": "integer", "description": "The id of the pricing plan." }, "name": { "type": "string", "description": "Name of the pricing plan." }, "sku": { "type": "string", "description": "SKU code associated with the pricing plan." } } }, "PricingList": { "type": "object", "properties": { "current_page": { "type": "integer", "description": "Current page number" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pricing" }, "description": "Available pricing plans." }, "from": { "type": "integer", "description": "First pricing index on the current page" }, "last_page": { "type": "integer", "description": "Total number of pages" }, "next_page_url": { "type": "string", "format": "uri", "description": "URL of the next page (if available)" }, "per_page": { "type": "integer", "description": "Number of pricings per page" }, "to": { "type": "integer", "description": "Last pricing index on the current page" }, "total": { "type": "integer", "description": "Total number of pricings" } } }, "User": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the user." }, "name": { "type": "string", "description": "Full name of the user." }, "email": { "type": "string", "format": "email", "description": "Email address of the user." }, "email_verified_at": { "type": "string", "format": "date-time", "description": "Timestamp when the email was verified." }, "address": { "type": "string", "nullable": true, "description": "User's address." }, "zip": { "type": "string", "nullable": true, "description": "Postal code of the user." }, "city": { "type": "string", "nullable": true, "description": "City of the user." }, "country": { "type": "string", "nullable": true, "description": "Country of the user." }, "phone": { "type": "string", "nullable": true, "description": "Phone number of the user." }, "contact": { "type": "string", "nullable": true, "description": "Alternative contact information." }, "vat": { "type": "string", "nullable": true, "description": "VAT number of the user, if applicable." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp of the user." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp of the user." }, "balance": { "type": "number", "description": "The user credits balance." }, "heuristic": { "type": "string", "description": "User's heuristic setting." }, "readonly": { "type": "boolean", "description": "User can only view classification results." }, "pricing": { "$ref": "#/components/schemas/Pricing", "description": "User pricing plan." }, "partner": { "$ref": "#/components/schemas/User", "description": "User partner." } } }, "C2PA": { "type": "object", "properties": { "manifests": { "type": "object", "description": "Dictionary of C2PA manifests, keyed by manifest URN. Each manifest contains information about the content's creation and modification history.", "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "description": "URN identifier for this manifest" }, "title": { "type": "string", "description": "Human-readable title of the manifest" }, "assertions": { "type": "array", "description": "List of cryptographic assertions about the content", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Type of assertion (e.g., 'c2pa.actions.v2')" }, "data": { "type": "object", "description": "Assertion data content" } } } }, "ingredients": { "type": "array", "description": "List of source materials used to create this content", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Type of ingredient" }, "title": { "type": "string", "description": "Name of the ingredient" }, "format": { "type": "string", "description": "File format of the ingredient" }, "relationship": { "type": "string", "description": "Relationship to the parent content (e.g., 'componentOf')" }, "active_manifest": { "type": "string", "description": "URN of the ingredient's active manifest" }, "validation_results": { "type": "object", "description": "Validation results for this ingredient" } } } }, "instance_id": { "type": "string", "description": "XMP instance ID" }, "signature_info": { "type": "object", "description": "Information about the cryptographic signature", "properties": { "alg": { "type": "string", "description": "Signature algorithm used (e.g., 'Es256')" }, "issuer": { "type": "string", "description": "Certificate issuer" }, "common_name": { "type": "string", "description": "Common name from the certificate" }, "cert_serial_number": { "type": "string", "description": "Certificate serial number" } } }, "claim_generator_info": { "type": "array", "description": "Information about the software that generated the claim", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the claim generator software" } } } } } } }, "active_manifest": { "type": "string", "description": "URN of the currently active manifest" }, "validation_state": { "type": "string", "enum": [ "Valid", "Invalid", "Unknown" ], "description": "Overall validation state of the C2PA data" }, "validation_status": { "type": "array", "description": "List of validation status messages", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URN or URL of the validated element" }, "code": { "type": "string", "description": "Validation status code" }, "explanation": { "type": "string", "description": "Human-readable explanation of the validation result" } } } }, "validation_results": { "type": "object", "description": "Detailed validation results", "properties": { "activeManifest": { "type": "object", "properties": { "failure": { "type": "array", "description": "List of validation failures", "items": { "type": "object" } }, "success": { "type": "array", "description": "List of successful validations", "items": { "type": "object" } }, "informational": { "type": "array", "description": "Informational validation messages", "items": { "type": "object" } } } }, "ingredientDeltas": { "type": "array", "description": "Validation deltas for ingredients", "items": { "type": "object" } } } } } }, "UserList": { "type": "object", "properties": { "current_page": { "type": "integer", "description": "Current page number" }, "data": { "type": "array", "description": "List of users on the current page", "items": { "$ref": "#/components/schemas/User" } }, "from": { "type": "integer", "description": "First user index on the current page" }, "last_page": { "type": "integer", "description": "Total number of pages" }, "next_page_url": { "type": "string", "format": "uri", "description": "URL of the next page (if available)" }, "per_page": { "type": "integer", "description": "Number of users per page" }, "to": { "type": "integer", "description": "Last user index on the current page" }, "total": { "type": "integer", "description": "Total number of users" } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "name": "X-Api-Key", "in": "header", "description": "Your API key." } } } }