{
  "openapi": "3.0.3",
  "info": {
    "title": "Resemble Detect + Intelligence API",
    "version": "2.0",
    "description": "Deepfake detection, media intelligence, audio source tracing, watermarking, and speaker identity from Resemble AI. Scope: Detect + Intelligence only (no TTS / voice cloning). Most jobs are asynchronous \u2014 submit, then poll the resource until `status` is `completed`/`failed`, or supply a `callback_url`. Response payloads are wrapped as `{ \"success\": true, \"item\": { ... } }`.\n",
    "contact": {
      "name": "Resemble AI",
      "url": "https://www.resemble.ai"
    }
  },
  "servers": [
    {
      "url": "https://app.resemble.ai/api/v2",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Detect",
      "description": "Deepfake / synthetic-media detection."
    },
    {
      "name": "Intelligence",
      "description": "Structured media analysis and Q&A."
    },
    {
      "name": "Source Tracing",
      "description": "Identify which AI platform generated fake audio."
    },
    {
      "name": "Watermark",
      "description": "Apply and detect invisible provenance watermarks."
    },
    {
      "name": "Identity",
      "description": "Speaker identity profiles and matching (beta)."
    }
  ],
  "paths": {
    "/detect": {
      "post": {
        "tags": [
          "Detect"
        ],
        "operationId": "createDetection",
        "summary": "Submit media for deepfake detection",
        "description": "Submit a public HTTPS media URL (audio, image, or video) for AI-generated / manipulated-content analysis. Returns a job; poll `GET /detect/{uuid}` until `status` is `completed`. Optional flags add intelligence, source tracing, and visualizations.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DetectRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Detection job created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DetectionEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "get": {
        "tags": [
          "Detect"
        ],
        "operationId": "listDetections",
        "summary": "List detections",
        "responses": {
          "200": {
            "description": "A page of detections.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Detection"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/detect/{uuid}": {
      "get": {
        "tags": [
          "Detect"
        ],
        "operationId": "getDetection",
        "summary": "Get a detection result",
        "parameters": [
          {
            "$ref": "#/components/parameters/Uuid"
          }
        ],
        "responses": {
          "200": {
            "description": "The detection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DetectionEnvelope"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/intelligence": {
      "post": {
        "tags": [
          "Intelligence"
        ],
        "operationId": "createIntelligence",
        "summary": "Analyze media for structured intelligence",
        "description": "Standalone media analysis (transcription, translation, speaker info, emotion, scene description, misinformation). Provide `url` or a secure-upload `media_token`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IntelligenceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Intelligence result (or job).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntelligenceEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/intelligences": {
      "get": {
        "tags": [
          "Intelligence"
        ],
        "operationId": "listIntelligences",
        "summary": "List intelligence analyses",
        "responses": {
          "200": {
            "description": "A page of analyses.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/intelligences/{uuid}": {
      "get": {
        "tags": [
          "Intelligence"
        ],
        "operationId": "getIntelligence",
        "summary": "Get an intelligence analysis",
        "parameters": [
          {
            "$ref": "#/components/parameters/Uuid"
          }
        ],
        "responses": {
          "200": {
            "description": "The analysis.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntelligenceEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/detects/{uuid}/intelligence": {
      "post": {
        "tags": [
          "Intelligence"
        ],
        "operationId": "askDetectionQuestion",
        "summary": "Ask a question about a completed detection",
        "description": "Ask a natural-language question grounded in a completed detection. Returns a question job; poll `GET /detects/{uuid}/intelligence/{question_uuid}` for the answer. The detection must be `completed` (otherwise 422).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/Uuid"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "The question to ask."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Question job created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuestionEnvelope"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/detects/{uuid}/intelligence/{question_uuid}": {
      "get": {
        "tags": [
          "Intelligence"
        ],
        "operationId": "getDetectionAnswer",
        "summary": "Get the answer to a detection question",
        "parameters": [
          {
            "$ref": "#/components/parameters/Uuid"
          },
          {
            "name": "question_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The answer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuestionEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/audio_source_tracings": {
      "get": {
        "tags": [
          "Source Tracing"
        ],
        "operationId": "listSourceTracings",
        "summary": "List audio source-tracing reports",
        "responses": {
          "200": {
            "description": "A page of reports."
          }
        }
      }
    },
    "/audio_source_tracings/{uuid}": {
      "get": {
        "tags": [
          "Source Tracing"
        ],
        "operationId": "getSourceTracing",
        "summary": "Get an audio source-tracing report",
        "parameters": [
          {
            "$ref": "#/components/parameters/Uuid"
          }
        ],
        "responses": {
          "200": {
            "description": "The report.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "item": {
                      "type": "object",
                      "properties": {
                        "label": {
                          "type": "string",
                          "example": "elevenlabs"
                        },
                        "error_message": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/watermark/apply": {
      "post": {
        "tags": [
          "Watermark"
        ],
        "operationId": "applyWatermark",
        "summary": "Apply an invisible watermark",
        "description": "Embed an invisible watermark for provenance. Send `Prefer: wait` for a synchronous response; otherwise poll `GET /watermark/apply/{uuid}/result`. Works reliably for audio; some image/video inputs are unsupported.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/PreferWait"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WatermarkApplyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Watermarked media.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WatermarkApplyEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/watermark/apply/{uuid}/result": {
      "get": {
        "tags": [
          "Watermark"
        ],
        "operationId": "getWatermarkApplyResult",
        "summary": "Get a watermark-apply result",
        "parameters": [
          {
            "$ref": "#/components/parameters/Uuid"
          }
        ],
        "responses": {
          "200": {
            "description": "The watermarked media.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WatermarkApplyEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/watermark/detect": {
      "post": {
        "tags": [
          "Watermark"
        ],
        "operationId": "detectWatermark",
        "summary": "Detect a watermark",
        "description": "Check whether media carries a Resemble watermark. Send `Prefer: wait` for a synchronous response. For audio, `metrics.has_watermark` is a per-channel object.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/PreferWait"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Detection result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WatermarkDetectEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/identity": {
      "post": {
        "tags": [
          "Identity"
        ],
        "operationId": "createIdentity",
        "summary": "Create a voice identity profile (beta)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "audio_url",
                  "name"
                ],
                "properties": {
                  "audio_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The created identity."
          }
        }
      },
      "get": {
        "tags": [
          "Identity"
        ],
        "operationId": "listIdentities",
        "summary": "List identity profiles (beta)",
        "responses": {
          "200": {
            "description": "A page of identities."
          }
        }
      }
    },
    "/identity/search": {
      "post": {
        "tags": [
          "Identity"
        ],
        "operationId": "searchIdentity",
        "summary": "Match audio against known identities (beta)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "audio_url"
                ],
                "properties": {
                  "audio_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "top_k": {
                    "type": "integer",
                    "default": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked matches.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "item": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "uuid": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "confidence": {
                            "type": "number"
                          },
                          "distance": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Resemble API key: `Authorization: Bearer <RESEMBLE_API_KEY>`"
      }
    },
    "parameters": {
      "Uuid": {
        "name": "uuid",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "PreferWait": {
        "name": "Prefer",
        "in": "header",
        "required": false,
        "description": "Set to `wait` for a synchronous response.",
        "schema": {
          "type": "string",
          "enum": [
            "wait"
          ]
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Invalid or missing API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unprocessable": {
        "description": "Detection not completed yet.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "message": {
            "type": "string"
          }
        }
      },
      "DetectRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Public HTTPS URL to the media."
          },
          "callback_url": {
            "type": "string",
            "format": "uri",
            "description": "Async completion webhook."
          },
          "intelligence": {
            "type": "boolean",
            "description": "Run intelligence alongside detection."
          },
          "audio_source_tracing": {
            "type": "boolean",
            "description": "Trace which AI generated fake audio."
          },
          "visualize": {
            "type": "boolean",
            "description": "Generate heatmap artifacts."
          },
          "use_reverse_search": {
            "type": "boolean",
            "description": "Image-only reverse search."
          },
          "use_ood_detector": {
            "type": "boolean",
            "description": "Out-of-distribution detection."
          },
          "zero_retention_mode": {
            "type": "boolean",
            "description": "Auto-delete media after analysis."
          },
          "model_types": {
            "type": "string",
            "enum": [
              "image",
              "talking_head"
            ],
            "description": "Force a model."
          },
          "frame_length": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4,
            "default": 2
          },
          "start_region": {
            "type": "number"
          },
          "end_region": {
            "type": "number"
          }
        }
      },
      "DetectionEnvelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "item": {
            "$ref": "#/components/schemas/Detection"
          }
        }
      },
      "Detection": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "processing",
              "completed",
              "failed"
            ]
          },
          "media_type": {
            "type": "string",
            "enum": [
              "audio",
              "image",
              "video"
            ]
          },
          "url": {
            "type": "string"
          },
          "metrics": {
            "type": "object",
            "description": "Audio metrics.",
            "properties": {
              "label": {
                "type": "string",
                "enum": [
                  "real",
                  "fake"
                ]
              },
              "score": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "aggregated_score": {
                "type": "string"
              },
              "consistency": {
                "type": "string"
              }
            }
          },
          "image_metrics": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "score": {
                "type": "number"
              },
              "ifl": {
                "type": "object",
                "properties": {
                  "score": {
                    "type": "number"
                  },
                  "heatmap": {
                    "type": "string",
                    "description": "Inline base64 data URI."
                  }
                }
              }
            }
          },
          "video_metrics": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "score": {
                "type": "number"
              },
              "certainty": {
                "type": "number"
              }
            }
          },
          "audio_source_tracing": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "error_message": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "intelligence": {
            "type": "object"
          }
        }
      },
      "IntelligenceRequest": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "media_token": {
            "type": "string"
          },
          "detect_id": {
            "type": "string"
          },
          "media_type": {
            "type": "string",
            "enum": [
              "audio",
              "video",
              "image"
            ]
          },
          "json": {
            "type": "boolean",
            "default": true
          },
          "callback_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "IntelligenceEnvelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "item": {
            "type": "object",
            "properties": {
              "uuid": {
                "type": "string"
              },
              "description": {
                "type": "object",
                "description": "Structured fields (vary by media type)."
              }
            }
          }
        }
      },
      "QuestionEnvelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "item": {
            "type": "object",
            "properties": {
              "uuid": {
                "type": "string"
              },
              "query": {
                "type": "string"
              },
              "answer": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "processing",
                  "completed",
                  "failed"
                ]
              }
            }
          }
        }
      },
      "WatermarkApplyRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "strength": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "default": 0.2
          },
          "custom_message": {
            "type": "string",
            "default": "resembleai"
          }
        }
      },
      "WatermarkApplyEnvelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "item": {
            "type": "object",
            "properties": {
              "uuid": {
                "type": "string"
              },
              "media_type": {
                "type": "string"
              },
              "watermarked_media": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "WatermarkDetectEnvelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "item": {
            "type": "object",
            "properties": {
              "uuid": {
                "type": "string"
              },
              "media_type": {
                "type": "string"
              },
              "metrics": {
                "type": "object",
                "properties": {
                  "has_watermark": {
                    "description": "Boolean, or per-channel object for audio.",
                    "oneOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "object",
                        "additionalProperties": {
                          "type": "boolean"
                        }
                      }
                    ]
                  },
                  "model": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}