Video

Ask a video a question

The endpoint everything else is built on. Ask a question about a video and get the answer in words, with the second of every moment it names.

Omit question and the answer covers the complete video, second zero to the end.

The answer carries a session_id. Pass it with the next question about the same video and that question reads what was already found instead of watching the video again: a few hundred tokens where the first one was a few thousand, and a second rather than a minute.

A first question takes 30 to 90 seconds, because nobody has looked at the video yet. Every question after it is short.

post/v1/watch_video

Request

  • Base URL: https://api.tryplayhead.com
  • URL: https://api.tryplayhead.com/v1/watch_video
  • Auth: HTTP bearer

Request body

urlstring

A platform link, a direct media URL, or an upl_… id from an upload. Omit it when you pass a session_id.

upload_idstring

The id returned by POST /v1/uploads.

session_idstring

The conversation about one video, from an earlier answer. It is what makes a follow-up cheap.

questionstring

What you want to know. Omit it for what happens across the complete video.

contextstring[]

What you already know and the video cannot show: what the person is building, and what they asked. Plain sentences. It costs almost nothing and the answer is better for it.

regionnumber[]

The part of the picture to read, as [x0, y0, x1, y1] in fractions of the frame. Use it with window for a follow-up about one corner of one moment: window says when, region says where. [0.5, 0, 1, 0.5] is the top right quarter. Fractions rather than pixels, so the same question works on a landscape recording and a vertical one.

instructionsstring

How the answer should read. Replaces our own wording rules.

schemaobject

A JSON Schema. The answer then comes back in value, in that shape, and a field the video cannot fill is null with its reason in unanswered.

rewatchboolean

Watch the whole video again and pay for it again. Only after an answer stated the price.

idempotency_keystring

Replaying the same key returns the first answer rather than charging twice.

Response

The answer, in words.

session_idstring

Pass this with the next question about the same video.

answerstring

The reading, in words, with the second of every moment it names.

valueobject nullable

Present when a schema was passed.

cachedboolean

True when this exact question had been answered before. It then costs nothing.

seen_atnumber[]

The seconds this answer was read from.

credits_chargednumber
out_of_creditsboolean

True when this answer cost more than the balance held. You were charged what was left, and the next reading is refused until you add credits.

msinteger

Wall-clock milliseconds.

Changes

No recorded changes to this operation across all 1 revision of this API.