Analyze Video

Ask a Gemini model a question about a video of at most 180 seconds, given as a public HTTPS url or an uploaded asset_id (at most 50 MB) or inline base64 (at most 16 MB), in MP4, MOV, WebM or MPEG. model picks the model and prompt asks the question. With a response_schema (a JSON Schema whose root is an object) the answer is JSON that validates against it; without one it is text. The request answers 202 with the job, pending or processing, and the analysis finishes whether or not it is read: read it with GET /v3/video-analyses/{analysis_id} until it is completed with its output, or failed with a failure_code. Send Prefer: wait=N (at most 50 seconds) to hold the request until the analysis finishes: it then answers 200 with the finished job and a Preference-Applied header, or 202 if it is still running when the wait ends. Before the model runs, the workspace's API credits must cover the most the model can cost: the frames sampled from the video, its audio, the prompt and schema, and every one of max_output_tokens, on top of the same for the workspace's analyses still running; a request they cannot cover is refused with 402 insufficient_credit and nothing is charged. Once the model has answered, the cost it reported for the call is charged. If the balance can no longer pay it then, the analysis fails with insufficient_credit, its answer is not returned, and a request reading it through Prefer: wait or a replay gets 402. Three failures are charged, because the model ran and wrote: output_not_json (an answer that is not JSON matching response_schema, or was cut off at max_output_tokens), no_answer (the model wrote nothing it could return, for example when its thinking used the whole allowance) and vendor_timeout once the video had reached the model. Each is charged the cost the model reported, or, when it reported none, the most the request could cost, and its answer is not returned. Any other failed analysis is not charged. A video that is too long or in another format is refused with 400. Send an Idempotency-Key header with every request: it is required. Repeating a request with the same key and body returns the original job without charging or analyzing again, and the same key with a different body gets 409 conflict. A job still unfinished 30 minutes after it was created is failed by the next read, and refunded if its charge had started. HyperFrames Desktop may call it with its OAuth token instead of an API key: its analyses are paid from the HyperFrames plan by the same rules, and a request the plan cannot pay is refused before any work with 403 api_key_required (the plan does not pay for this work; send it with an API key) or 402 hf_usage_exhausted or hf_subscription_required.