API docs by Redocly

TruffleTV Contextual Targeting API (1.0.0)

Download OpenAPI specification:

TruffleTV's API enables advanced, privacy-first contextual targeting for Connected TV (CTV) advertising. Key features include scene-level precision, multimodal AI analysis, emotional resonance targeting, dynamic ad creative optimization, flexible taxonomy-free targeting, in-video object and facial analysis, brand and logo recognition, activity and behaviour recognition, advanced speech and sound analysis, product recognition, attention and gaze tracking, cross-platform content matching, and holistic multimodal analysis.

Content Analysis

Multimodal scene-level content analysis and recognition

Scene-level multimodal content analysis

Analyze a video asset using multimodal AI (visual, audio, text) to extract scene-level context, emotional resonance, abstract concepts, and more for targeting.

Authorizations:
OAuth2
Request Body schema: application/json
required
contentId
required
string
videoUrl
required
string <uri>
required
object

Responses

Request samples

Content type
application/json
{
  • "contentId": "string",
  • "videoUrl": "http://example.com",
  • "metadata": {
    }
}

Retrieve scene-level analysis results

Authorizations:
OAuth2
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "contentId": "string",
  • "scenes": [
    ]
}

Detect objects in video content

Analyze a video asset to detect and localize objects frame-by-frame or scene-by-scene. Returns bounding boxes, object classes, and timestamps for each detected object.

Authorizations:
OAuth2
Request Body schema: application/json
required
contentId
required
string
videoUrl
required
string <uri>
detectionClasses
Array of strings

Optional list of object classes to detect (e.g., ["car", "logo"])

Responses

Request samples

Content type
application/json
{}

Retrieve object detection results for a video

Authorizations:
OAuth2
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "contentId": "string",
  • "detectedObjects": [
    ]
}

Detect faces and facial attributes in video content

Analyze a video asset to detect faces, their bounding boxes, and facial attributes such as emotion, age group, and presence of glasses or headwear.

Authorizations:
OAuth2
Request Body schema: application/json
required
contentId
required
string
videoUrl
required
string <uri>
includeAttributes
boolean
Default: true

Whether to include facial attributes (emotion, glasses, etc.)

Responses

Request samples

Content type
application/json
{}

Retrieve facial analysis results for a video

Authorizations:
OAuth2
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "contentId": "string",
  • "detectedFaces": [
    ]
}

Detect brands and logos in video content

Analyze a video asset to detect and localize brands/logos, providing bounding boxes, brand names, and confidence scores for each occurrence.

Authorizations:
OAuth2
Request Body schema: application/json
required
contentId
required
string
videoUrl
required
string <uri>

Responses

Request samples

Content type
application/json
{}

Retrieve brand and logo detection results

Authorizations:
OAuth2
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "contentId": "string",
  • "detectedBrands": [
    ]
}

Detect human activities and behaviors in video

Identifies actions such as product use, engagement, or custom behaviors in video scenes using advanced action recognition models.

Authorizations:
OAuth2
Request Body schema: application/json
required
contentId
required
string
videoUrl
required
string <uri>
actionTypes
Array of strings

Optional list of action types to detect (e.g., ["product_use", "engagement"])

Responses

Request samples

Content type
application/json
{}

Retrieve action and behavior detection results

Authorizations:
OAuth2
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "contentId": "string",
  • "detectedActions": [
    ]
}

Advanced speech and sound analysis

Transcribes speech, detects brand mentions, analyzes sentiment, and recognizes key sounds for contextual targeting and brand safety.

Authorizations:
OAuth2
Request Body schema: application/json
required
contentId
required
string
audioUrl
required
string <uri>

Responses

Request samples

Content type
application/json
{}

Retrieve advanced audio analysis results

Authorizations:
OAuth2
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "contentId": "string",
  • "transcript": "string",
  • "brandMentions": [
    ],
  • "sentiment": "positive",
  • "keySounds": [
    ]
}

Detect products in video content

Identifies and localizes specific product models in video scenes for shoppable ad experiences.

Authorizations:
OAuth2
Request Body schema: application/json
required
contentId
required
string
videoUrl
required
string <uri>

Responses

Request samples

Content type
application/json
{}

Retrieve product detection results

Authorizations:
OAuth2
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "contentId": "string",
  • "detectedProducts": [
    ]
}

Attention and gaze tracking analysis

Analyzes video content to predict viewer attention, generate heatmaps, and provide gaze/focus metrics for optimizing ad placement and layout.

Authorizations:
OAuth2
Request Body schema: application/json
required
contentId
required
string
videoUrl
required
string <uri>

Responses

Request samples

Content type
application/json
{}

Retrieve attention and gaze tracking results

Authorizations:
OAuth2
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "contentId": "string",
  • "heatmapUrl": "http://example.com",
  • "attentionScores": [
    ]
}

Cross-platform content matching

Matches and tracks video content across multiple platforms/channels to monitor reuse, reach, and performance.

Authorizations:
OAuth2
Request Body schema: application/json
required
contentId
required
string
videoUrl
required
string <uri>
platforms
Array of strings

Optional list of platforms/channels to match against

Responses

Request samples

Content type
application/json
{}

Retrieve cross-platform content matching results

Authorizations:
OAuth2
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "contentId": "string",
  • "matches": [
    ]
}

Targeting

Flexible targeting, including taxonomy-free and emotional resonance queries

Flexible, taxonomy-free targeting query

Query for scenes or content segments matching abstract concepts (e.g., "family bonding"), emotional states, or logical context, without relying on predefined taxonomies.

Authorizations:
OAuth2
Request Body schema: application/json
required
concept
required
string

Abstract concept or context to target (e.g., "family bonding", "competition")

emotion
string

Target emotional state (optional)

confidenceThreshold
number <float>
Default: 0.7

Responses

Request samples

Content type
application/json
{
  • "concept": "string",
  • "emotion": "string",
  • "confidenceThreshold": 0.7
}

Response samples

Content type
application/json
{
  • "matches": [
    ]
}

Creative Optimization

Dynamic ad creative adaptation and optimization

Dynamic ad creative optimization

Automatically adapt ad creatives to fit the detected tone, context, and emotional resonance of a given scene.

Authorizations:
OAuth2
Request Body schema: application/json
required
creativeId
required
string
required
object

Responses

Request samples

Content type
application/json
{
  • "creativeId": "string",
  • "sceneContext": {
    }
}

Response samples

Content type
application/json
{
  • "creativeId": "string",
  • "recommendedVariants": [
    ]
}

Campaign Management

Campaign and targeting profile management