Why does a Gemini call fail immediately after uploading a video via the Files API?

## Upload is not availability The Files API separates *receiving* bytes from *preparing* them. For images and small documents preparation is effectively instantaneous, so the File comes back already `ACTIVE`. For video — and for large media generally — Google has server-side work to do first, and the upload call returns a File whose `state` is `PROCESSING`. A Part referencing a `PROCESSING` file is not queued or waited on. The generation request is rejected immediately with HTTP **400** and status **FAILED_PRECONDITION**, with a message to the effect that the file is not in an ACTIVE state. ## The correct pattern Upload, then loop: sleep a few seconds, re-fetch the file with `client.files.get(name=f.name)`, and continue while the state is `PROCESSING`. Only once it reports `ACTIVE` do you build the Part and call `generate_content`. Three details matter. First, poll with `files.get(name=f.name)` — the resource name (`files/abc123`), not the URI. Second, handle the third state: `FAILED` means the media could not be prepared at all (corrupt container, unsupported codec), and no amount of further polling will change it; the correct response is to surface the error or re-encode and re-upload, not to loop forever. Third, bound the loop — a wall-clock deadline plus a backoff, so a stuck file cannot pin a worker indefinitely. ## Why this bug hides Developers test with a small sample clip that becomes ACTIVE before the next line of code runs, so the missing poll loop is invisible. In production, real user uploads are minutes long, processing takes real time, and the failure appears as intermittent 400s that correlate suspiciously with file size. Any code path that uploads video without a state check should be treated as broken regardless of whether it has failed yet. ## The other end of the lifecycle: expiry Files are retained for **48 hours** and then deleted; the File resource carries an `expiration_time` you can read. A `file_uri` is therefore a short-lived handle. Systems that persist the URI as though it identified the document — in a database row, a job payload, a retry queue that might drain late — break silently two days later when the reference no longer resolves. The robust shape: your own object storage holds the authoritative bytes, and the Gemini file is a cache entry keyed by your document id. On a missing or expired file error, re-upload and retry once; only then surface a failure. That also handles the case where a file was deleted early, deliberately, by `client.files.delete(name=...)`. ## Scope and visibility Files belong to the project and API key that uploaded them. A URI minted by your staging key will not resolve for your production key, and a URI cannot be shared with another party as a download link — the API deliberately exposes metadata only, with no way to read the bytes back out. If several services need the same media, each needs its own upload, or one service owns Gemini interaction on behalf of the others. ## Quotas as a lifecycle concern Storage is free but bounded — on the order of 20 GB per project, with a 2 GB ceiling per file. A high-volume pipeline that uploads and never deletes will eventually hit the project cap even though everything expires eventually, because expiry lags ingestion. Explicitly deleting files once a job completes keeps headroom and is one line: `client.files.delete(name=f.name)`. ## What a strong answer sounds like Name the state machine (PROCESSING to ACTIVE, or FAILED), name the error you get for jumping the gun (400 FAILED_PRECONDITION), describe a bounded poll on `files.get`, and then connect it to the two adjacent lifecycle facts — 48-hour expiry making URIs non-durable, and project scoping making them non-portable. That combination shows someone who has actually run video through this API rather than read the quickstart.