Google Flow Agent API

October 16, 2026

Table of contents

  1. How a chat works
  2. Endpoints
  3. Credits and approvals
  4. References and @-mentions
  5. Project, instructions and defaults
  6. Limits
  7. Media links
  8. Errors
    1. Turn errors
  9. Usage stats

The useapi.net Google Flow Agent API lets your code chat with Google Flow Agent, the creative assistant built into Google Flow, on your own Google account. Send it a message with images, videos, voices and characters, follow its replies live, approve what it wants to spend, and collect the images and videos it makes.

The agent runs on Google’s side and keeps the whole conversation there. You can come back to a chat hours or days later and it still has the full context. Chats you start through the API show up in the Flow web app, and chats started in the web app show up in the API when they are in the same project.

The agent plans, writes, generates and edits images and videos, extends videos, describes media you attach, and organizes the project’s media into collections when you ask it to. It picks its own tools and models, guided by the project’s instructions and defaults.

How a chat works

  1. Start a chat with POST /agent/chats. It answers 202 with a chatId once Google has accepted the turn.
  2. Follow the agent live with GET /agent/chats/chatId/stream, or read the chat at any time with GET /agent/chats/chatId, or get each turn posted to your replyUrl when it ends.
  3. When the agent wants to spend credits, it stops and asks. Answer with POST /agent/chats/chatId/approval.
  4. Send the next message with POST /agent/chats/chatId/messages.
  5. Collect the media. Images are ready when the turn ends. Videos usually finish a minute or two later: the stream sends a media event for each one, and GET shows its status and link.

A turn is one message from you and everything the agent does in reply. A chat runs one turn at a time.

Endpoints

Endpoint What it does
POST /agent/chats Start a chat with a message and optional references
POST /agent/chats/chatId/messages Send the next message
POST /agent/chats/chatId/approval Approve or reject the agent’s request to spend credits
GET /agent/chats/chatId/stream Follow the chat live over Server-Sent Events, resumable
GET /agent/chats/chatId Read the chat: every turn, the agent’s messages, media with links, and its state
GET /agent/chats List an account’s chats, including ones started in the Flow web app
PATCH /agent/chats/chatId Rename a chat
DELETE /agent/chats/chatId Delete a chat’s history (the media stay)
GET /agent/settings Read the project’s approval mode, instructions and default models
PUT /agent/settings Change them

All routes are under https://api.useapi.net/v1/google-flow/agent. They use your existing Google Flow accounts and captcha providers, with nothing new to set up.

Credits and approvals

Chatting with the agent costs no Flow credits. The images and videos it generates cost the usual Flow price, the same as POST /images and POST /videos.

Each project has an approval mode:

  • ask (the default): before it spends credits, the agent stops and shows the cost, for example cost: 10 for one 8-second Veo 3.1 Lite video. The chat’s status is waiting_approval until you answer with approve, always or reject. Sending a new message instead moves on without generating.
  • auto: the agent spends without asking. Answering an approval with always, or setting approval: "auto" with PUT /agent/settings, switches the project to it.

Each turn uses one captcha, the same as a generation request.

The agent works on every Google AI plan, including a free account. What it can generate follows the account’s plan, the same as POST /images and POST /videos.

References and @-mentions

Attach images, a video, voices and characters to any message with the same parameters and @-mention syntax as POST /videos: up to 7 referenceImage_N, 1 referenceVideo_1, 5 referenceAudio_N and 7 character_N. See POST /agent/chats for the details.

Everything the agent makes comes back with a referenceId. Use it in POST /images, POST /videos and in your next agent message.

Project, instructions and defaults

Every chat lives in a Flow project. Unless you pass projectId, the API uses a dedicated project per account, created on the account’s first chat and named like My Agents Work Fri, Oct 16. Keeping agent chats there keeps them apart from your other Flow media. Pass projectId (from GET /assets/projects/email) to chat in another project.

Each project has its own agent settings, read with GET /agent/settings and changed with PUT /agent/settings:

  • the approval mode, ask or auto
  • up to 3 standing instructions the agent follows in every chat of the project, each with optional reference images
  • the default image model (nano-banana-pro or nano-banana-2), aspect ratio and number of images
  • the default video model (omni-flash or veo-3.1-lite-low-priority), aspect ratio and number of videos

The agent uses the defaults whenever a message does not say otherwise.

Limits

  • One turn at a time per chat. Sending while a turn runs answers 409.
  • At most 3 running turns per account. The next one answers 429 with Retry-After.
  • Google limits how many agent messages an account can send per day and does not publish the number. When an account reaches it, the API answers 429 for that account until midnight UTC. Use another account until then.
  • A turn can run for up to 10 minutes, Google’s own limit.

Media links in url point to Google and expire about 6 hours after they are issued. Read the chat again with GET /agent/chats/chatId for fresh links, or get a fresh link for one item from GET /assets/mediaGenerationId with its referenceId.

Errors

Code When
400 A parameter is missing or invalid, an @-mention has no matching parameter, or a reference belongs to another account.
401 Invalid API token.
403 The chatId belongs to another useapi.net user.
404 The chat was deleted or does not exist, or the account is not added.
409 A turn is already running in the chat, or nothing is waiting for approval. Rename and delete also answer 409 while a turn runs.
429 The account already runs 3 agent turns, or it reached Google’s daily limit on agent messages.
502 Google answered with an error or without a readable reply (reason GOOGLE_ERROR or UNREADABLE_ANSWER). The turn may have run: read the chat before you retry.
503 Google refused every captcha for the turn (reason CAPTCHA_FAILED), or your captcha provider failed. Nothing ran and nothing was charged.
504 Google has not confirmed the turn yet, and it may still start. Read the chat before you send it again.
596 The account’s Google session is no longer valid. Add the account again with POST /accounts.

Turn errors

After the 202, a turn can still fail. The stream’s turn event, lastError on GET /agent/chats/chatId and the replyUrl body carry its error as { code, message, httpStatus }:

code httpStatus What happened What to do
INTERRUPTED 502 or 500 The connection to Google broke during the turn. What the agent made so far is in the chat. Read the chat before you send the message again.
GOOGLE_ERROR Google’s status Google ended the turn with an error. What the agent made so far is in the chat. Read the chat before you retry.
UNREADABLE_ANSWER 502 Google answered without a readable reply and may already have run the turn. Read the chat before you retry.
TIMEOUT 504 The turn ran past Google’s 10-minute limit. What the agent made is in the chat. Send a follow-up such as continue.
CAPTCHA_FAILED 503 Google refused every captcha for the turn. Nothing ran and nothing was charged. Send the message again.
AGENT_QUOTA 429 The account reached Google’s daily limit on agent messages. Use another account, or wait until the next day (midnight UTC).

A failed turn may already have started images or videos. They are listed in the chat with their own status, and generated media cost the usual Flow credits. Except after CAPTCHA_FAILED, read the chat before you resend a failed turn.

Usage stats

Agent requests show in GET account/stats with bot=google-flow. Each turn is one row with model agent (endpoint execute, status completed, waiting_approval or failed), each answered approval has model agent-approval, and each stream opened has model agent-stream.