Brands

Brand detection finds brands on screen, in speech, and in the video's title, description and tags. Each brand comes back with a confidence and its appearances. Video length, fps and frames per job are capped per plan: see Limits.

curl -X POST https://api.netraflow.com/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_live_your_key_here" \
  -d '{
    "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "capabilities": ["brands"],
    "brands": ["Nike", "Adidas"],
    "surfaces": ["jersey"]
  }'

{
  "data": {
    "job_id": "job_abcdefghij123456",
    "status": "completed",
    "results": {
      "brands": [
        {
          "name": "nike",
          "raw_name": "Nike",
          "confidence": 0.95,
          "total_appearances": 3,
          "total_visible_duration": 8.4,
          "mark_seconds": 14.2,
          "peak_marks": 3,
          "first_seen": 12.5,
          "last_seen": 89.6,
          "surfaces": ["jersey"],
          "appearances": [
            {
              "timestamp": 12.5,
              "timestamp_start": 12.5,
              "timestamp_end": 20.9,
              "visible_duration": 8.4,
              "confidence": 0.95,
              "verified": true,
              "source": "visual",
              "surface": "jersey",
              "bounding_box": { "x": 0.3, "y": 0.2, "width": 0.15, "height": 0.1 },
              "frame_detections": [
                {
                  "timestamp": 12.5,
                  "bounding_box": { "x": 0.3, "y": 0.2, "width": 0.15, "height": 0.1 },
                  "mask": { "size": [144, 256], "counts": [20412, 31, 225, 36, 16160] }
                },
                {
                  "timestamp": 14.5,
                  "bounding_box": { "x": 0.33, "y": 0.21, "width": 0.14, "height": 0.1 },
                  "mask": { "size": [144, 256], "counts": [20671, 30, 226, 35, 15902] }
                }
              ]
            },
            {
              "timestamp": 89.0,
              "timestamp_start": 89.0,
              "timestamp_end": 89.6,
              "confidence": 0.82,
              "source": "audio",
              "context": "Mentioned in speech",
              "speech_context": "We partnered with Nike for this campaign."
            },
            {
              "source": "metadata",
              "confidence": 0.5,
              "context": "Mentioned in video metadata"
            }
          ]
        }
      ],
      "confidence_summary": { "high": 1, "medium": 0, "low": 0, "total": 1 }
    }
  }
}

Targeting

Both fields are optional. Without them, a job finds every brand it sees.

• surfaces narrows where brands are looked for, so the job is usually faster, cheaper and more precise. Each appearance carries its surface, and each brand a surfaces list.
• brands narrows what is reported, not what is looked at, so it doesn't make a job cheaper. A name you pass is looked for even if it is little known.

Surfaces you can target

Each row starts with its broadest surface.

Brand fields

total_visible_duration says how long a brand was showing; mark_seconds and peak_marks say how much of it. Nineteen boards for five seconds and one board for five seconds both have a total_visible_duration of 5, but mark_seconds of 95 and 5, and peak_marks of 19 and 1. A brand never on screen has 0 for all three. mark_seconds and peak_marks are absent on older results.

Appearance fields

Branch on source first. A metadata appearance is timeless: no timestamp, duration or box.

A visual appearance is one stretch of time the brand was on screen, however many of its marks were up. Stretches less than about a second apart are joined. On a surface-targeted job, stretches are per surface.

Frame detection fields

Older results may also carry confidence and confidence_kind on each detection. Ignore them: use the brand's confidence.

Visual evidence

With return_proof on (the default), a brands job adds a storyboard: up to 150 frames spread across the video, tiled into sheets. Tiles are plain frames. To show a brand, find the tile nearest a frame_detections timestamp and draw its bounding_box over it. See Frames. return_proof: false also drops speech_context.

Result signals

When brand detection can't run at all, see When one capability cannot run.

Frame rate and cost

Brand detection looks at 1 frame per second unless you pass fps. A higher rate catches marks that flash past and costs more. A lower rate mainly risks missing a brief mark. On a long video, fps is lowered to fit your plan's frames per job.

How brands are named

Everyday-word brands such as United, Square, Delta, Target, Apple and Meta are named only when the whole text is that word: a jersey reading "MANCHESTER UNITED" is not United. A longer name, such as Square Enix, is kept whole.

A few brands are reported under a shorter or longer name than the mark on screen, and name is that name in lowercase:

See also: Brand and logo detection, with real results.