{ "openapi": "3.0.1", "info": { "title": "Vision Check API", "summary": "An API for checking the context and authenticity of visual assets and managing those visionAnalyses", "description": "The Compass Vision API provides users with an endpoint to analyze an image by submitting its URL, returning a confidence score indicating whether the image is a deep fake or AI-generated. Upon submitting the image URL, the API processes it using advanced AI detection algorithms to evaluate features commonly associated with manipulated or synthetically generated visuals. \n\nThe response will include a confidence score, where a higher score indicates a higher likelihood that the image is a deep fake or AI-generated. This API is ideal for use in content moderation, authenticity verification, and media analysis tools.\n\nYou can try these out in your browser with the [OpenAPI Spec](https://api.blackbird.ai/compass/openapi/#/VisionAnalyses). Be sure to hit \"Authorize 🔓\" and enter your credentials first." }, "servers": [ { "url": "https://api.blackbird.ai/compass" } ], "x-hideTryItPanel": false, "x-codeSamples": true, "paths": { "/visionAnalyses": { "post": { "summary": "Create a new vision analysis", "description": "Creates a new vision analysis. The resource isn't fully created immediately and you'll want to poll the `/visionAnalyses/{id}` GET for the result.", "operationId": "createVisionAnalysis", "parameters": [ { "name": "cache-control", "in": "header", "required": false, "description": "Whether to bypass the cached response. Requires permission to bypass the cache.", "schema": { "type": "string", "enum": [ "no-cache" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVisionAnalysisRequest" } } } }, "responses": { "200": { "description": "Vision analysis accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessingVisionAnalysis" } } } } } }, "get": { "summary": "Gets all the vision analyses the caller has submitted.", "description": "Note that the result is eventually consistent with creation of a visionAnalysis, so you might not read your own write when you query for all visionAnalyses", "operationId": "getVisionAnalyses", "parameters": [ { "name": "start", "in": "query", "required": false, "allowReserved": true, "schema": { "type": "string", "format": "date-time" }, "description": "Filter vision analyses created after this date (inclusive with ascending sort order, exlusive with descending sort order)" }, { "name": "end", "in": "query", "required": false, "allowReserved": true, "schema": { "type": "string", "format": "date-time" }, "description": "Filter vision analyses created before this date (exclusive with ascending sort order, inclusive with descending sort order)" }, { "name": "offsetKey", "in": "query", "required": false, "allowReserved": true, "schema": { "type": "string" }, "description": "The identifier for the offset to start at. Use the nextOffsetKey from the prior page to get the next page." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "The direction to sort vision analyses by created_at" } ], "responses": { "200": { "description": "Vision Analyses found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionAnalysesQueryResponse" } } } } } } }, "/visionAnalyses/{id}": { "get": { "summary": "Get input and analysis", "description": "Retrieves the vision analysis with the input and the generated analysis around it", "operationId": "getVisionAnalysis", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the vision analysis to retrieve.", "example": "914e5150-7a8c-40a7-b0d9-4738e9d31f9e" } ], "responses": { "200": { "description": "Vision Analysis found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionAnalysis" } } } }, "404": { "description": "Vision Analysis not found" } } } } }, "components": { "securitySchemes": { "oAuth2Password": { "type": "oauth2", "flows": { "password": { "tokenUrl": "https://api.blackbird.ai/compass/token", "scopes": {} } } }, "clientCredentials": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://api.blackbird.ai/auth/oauth2/token", "scopes": {} } } } }, "schemas": { "VisualizationType": { "type": "string", "enum": [ "heatmap", "bounding_box" ], "description": "The type of annotation to apply to the frames of the video." }, "VisionAnalysisOptions": { "type": "object", "required": [ "explain" ], "additionalProperties": false, "properties": { "explain": { "type": "boolean", "description": "Whether to explain the vision analysis result when there is anything worth explaining or not.", "default": false }, "isVideo": { "type": "boolean", "description": "Whether to use video analysis, requires an additional permission and is rate limited separately", "default": false }, "needFramesAnnotation": { "type": "boolean", "description": "Whether to annotate the frames of the video with a heatmap or bounding box.", "default": false }, "framesAnnotationType": { "type": "array", "description": "The type of annotation to apply to the frames of the video. Only one value is supported at a time.", "minItems": 0, "maxItems": 1, "items": { "$ref": "#/components/schemas/VisualizationType" } } } }, "BaseVisionAnalysis": { "type": "object", "required": [ "id", "created_at", "updated_at", "status", "input", "options" ], "properties": { "id": { "type": "string", "description": "The ID of the vision analysis", "example": "7bf34023-641f-4191-a836-8cd4716266f3" }, "created_at": { "type": "string", "format": "date-time", "description": "The datetime the vision analysis was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "The datetime the vision analysis was last updated." }, "input": { "type": "string", "format": "url", "description": "The input to generate a vision analysis of" }, "options": { "$ref": "#/components/schemas/VisionAnalysisOptions" }, "status": { "type": "string", "description": "The status of the vision analysis generation" } } }, "ProcessingVisionAnalysis": { "allOf": [ { "$ref": "#/components/schemas/BaseVisionAnalysis" }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processing" ] } }, "example": { "id": "7bf34023-641f-4191-a836-8cd4716266f3", "input": "https://blackbird.ai/wp-content/uploads/2024/09/GU-BlknW0AA78y0-1.jpeg", "options": { "explain": true, "needFramesAnnotation": true, "framesAnnotationType": [ "heatmap" ] }, "created_at": "2024-10-10T13:01:29.822Z", "updated_at": "2024-10-10T13:01:29.822Z", "status": "processing" } } ] }, "VisionAnalysisData": { "type": "object", "required": [ "fake" ], "properties": { "fake": { "type": "object", "description": "The analysis of whether the content is fake and why it is determined to be/not-be fake", "required": [ "confidence", "isFake" ], "properties": { "confidence": { "type": "number", "description": "Represents the model's certainty about the classification expressed as a value between 0.5 and 1, where a higher value indicates higher confidence" }, "isFake": { "type": "boolean", "description": "Whether the content is fake or not." }, "explanation": { "type": "string", "description": "Why the content is considered fake. ONLY returned if the content was determined to be fake. NOT returned if the content was determined to be real" }, "annotations": { "type": "object", "description": "The annotations of the content. ONLY returned if the content was determined to be fake. NOT returned if the content was determined to be real", "properties": { "url": { "type": "string", "description": "The URL of the annotation" }, "format": { "type": "string", "enum": [ "jpeg", "mp4" ], "description": "The format of the annotation" }, "type": { "type": "string", "enum": [ "video" ], "description": "The type of the annotation" }, "height": { "type": "number", "description": "The height of the annotation" }, "width": { "type": "number", "description": "The width of the annotation" } } } } } } }, "SuccessfulVisionAnalysis": { "allOf": [ { "$ref": "#/components/schemas/BaseVisionAnalysis" }, { "type": "object", "required": [ "analysis" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "analysis": { "$ref": "#/components/schemas/VisionAnalysisData" } }, "example": { "updated_at": "2024-10-10T13:01:32.890Z", "created_at": "2024-10-10T13:01:29.822Z", "status": "success", "input": "https://x.com/i/status/1868091847064932761", "options": { "explain": true, "needFramesAnnotation": true, "framesAnnotationType": [ "heatmap" ] }, "id": "7bf34023-641f-4191-a836-8cd4716266f3", "analysis": { "fake": { "isFake": true, "confidence": 1, "explanation": "The image appears to show signs of being manipulated. The lighting on the face and surrounding elements lacks consistency, suggesting artificial enhancement. The reflections on the laptop screen are unusually sharp and do not match the soft ambient light from the room. Additionally, the smoothness of the model's skin appears overly perfected, which is an indicator of potential digital alteration. The presence of the stickers on the laptop lacks natural wear, which can further suggest artificiality, reinforcing the classification as a fake.", "annotations": [ { "url": "https://compass-vision-uploads.s3.us-west-2.amazonaws.com/hybrid_deepfake_video_annotation/39e0cd4f-e9e1-4d1c-94e9-6bafc3054a6f.mp4?AWSAccessKeyId=ASIA5SOOCSZGWOMA3HRE&Signature=v%2FaY%2BFreqi7Orx%2F56ToQYD8v7VU%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEG0aCXVzLXdlc3QtMiJHMEUCIBwB4bJO8Xf2MrdleRmSLr%2FtA%2BMEAQS84EyhxNMgfObaAiEAunh1iFTqbnzjpNrWFa2WVTV6CSlMV75uGV38IUb6GTgqrQIIRhADGgw5MzI5NzY5NTcwMDUiDK2VWa39Mw0m8BugSSqKAuUTyrLLpLFNHLiGPg8SVF6RjRmfagP6G48zrOKALGx0oWoJAltJo7FyRnzYSab5ntxuZzpZen50htUCKOGgv0TXlVGbCyCP%2FwWqniOgpkgbaZqU2tOHzw%2Fwwej8niGM6eXVAMGm3kcyDSJahaP5YLLkbDGAlAW0%2FMoQ415QtmLpPmC1G%2FngMTmlNiDSfrBFX384d2vhkRFa2FelXBQ9kRrNo49CWp2ad6FeIgUxHetsvLVFDQpMO%2FmJrWFHHZN9uhKpsfjl%2B%2B4Wx1D0%2BHHyrsE%2FszZeZSdM%2FdPtNfxsbWSk63F1rSCb5iIgMzQRbLREs1LzO94XwikYKYHc6%2FoXX1MTQB5%2BMFZAI%2BuuMJ2uhsIGOp0B1IUz8wTP8c8sTN%2B%2FNS5cbPN5XmHS3V4S5WUllmvGwUxoDvdh%2BD%2BlFiBkzwET3iWSJ0N%2Btc4IGou6WifusWQffKCN%2BTSICGJ0FzIUWkJTrTCwL3Kxv1DUaqrQECNg37LnrTX%2BETvSMDK12a62gB%2FDYrQ7j2s0zJMjMCR%2BB%2FPXLufDGRpcYj9nNxLMiDEn9NK%2B1NYr3IywQXFqSXUbmw%3D%3D&Expires=1749217063", "format": "jpeg", "type": "image", "height": 1000, "width": 1000 } ] } } } } ] }, "FailureVisionAnalysis": { "allOf": [ { "$ref": "#/components/schemas/BaseVisionAnalysis" }, { "type": "object", "required": [ "error" ], "properties": { "status": { "type": "string", "enum": [ "failed" ] }, "errorCode": { "type": "string", "enum": [ "invalidInput", "invalidContent", "corruptContent", "unsupportedFileType", "unableToRetrieveData", "serverError" ], "description": "The codified reason the request couldn't be completed: \n- invalidInput: The input was not a resolvable URL\n- invalidContent: The content did not meet the required size, resolution, or color constraints\n- corruptContent: The content could not be parsed as it's specified filetype\n- unsupportedFileType: The URL is to a file type that is not supported\n- unableToRetrieveData: The URL did not return data in a timely fashion\n- serverError: An unexpected problem occurred. Check again later.\n" }, "error": { "type": "string", "example": "There was an error processing your vision analysis." } }, "example": { "id": "7bf34023-641f-4191-a836-8cd4716266f3", "input": "https://example.com/not/an/image", "options": { "explain": true }, "created_at": "2024-10-10T13:01:29.822Z", "updated_at": "2024-10-10T13:01:29.822Z", "status": "failed", "error": "Couldn't download image" } } ] }, "VisionAnalysis": { "oneOf": [ { "$ref": "#/components/schemas/ProcessingVisionAnalysis" }, { "$ref": "#/components/schemas/SuccessfulVisionAnalysis" }, { "$ref": "#/components/schemas/FailureVisionAnalysis" } ], "discriminator": { "propertyName": "status", "mapping": { "processing": "#/components/schemas/ProcessingVisionAnalysis", "success": "#/components/schemas/SuccessfulVisionAnalysis", "failed": "#/components/schemas/FailureVisionAnalysis" } } }, "VisionAnalysesQueryResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VisionAnalysis" } }, "nextOffsetKey": { "type": "string", "description": "The offset key of the next page of data." } } }, "CreateVisionAnalysisRequest": { "type": "object", "required": [ "input" ], "additionalProperties": false, "properties": { "input": { "type": "string", "format": "url", "description": "The input to generate a vision analysis of. Images must have a minumum width and height of 200px and maximum width and height of 4000px. The following file formats are supported - PNG, JPEG, JPG, JPEG 2000, WebP, BMP, GIF, TIFF, TIF, DIB, ICO, EPS, PSD, PPM, PGM, PBM, PNM, TGA, XBM", "x-image-constraints": { "minWidth": 200, "minHeight": 200, "maxWidth": 4000, "maxHeight": 4000, "formats": [ "PNG", "JPEG", "JPG", "JPEG 2000", "WebP", "BMP", "GIF", "TIFF", "TIF", "DIB", "ICO", "EPS", "PSD", "PPM", "PGM", "PBM", "PNM", "TGA", "XBM", "MP4" ] } }, "options": { "$ref": "#/components/schemas/VisionAnalysisOptions" } }, "example": { "input": "https://blackbird.ai/wp-content/uploads/2024/09/GU-BlknW0AA78y0-1.jpeg", "options": { "explain": true, "isVideo": false, "needFramesAnnotation": false, "framesAnnotationType": [ "heatmap" ] } } } } }, "security": [ { "clientCredentials": [] }, { "oAuth2Password": [] } ] }