Send a message

October 16, 2026

Table of contents

  1. Request Headers
  2. Request Body
  3. Responses
  4. Model
  5. Examples
  6. Try It

Send the next message in a chat started with POST /agent/chats. Google keeps the whole conversation, so the agent has full context even days later. The chat runs on its own account and project, so this request takes no email or projectId.

A chat runs one turn at a time. Sending while a turn runs answers 409. When the agent is waiting for an approval, a new message moves on without generating: answer the approval with POST /agent/chats/chatId/approval if you want it to go ahead. To answer one of the agent’s choices, send the text of the choice as the message, as the Flow web app does.

The request answers 202 as soon as Google has accepted the turn. That usually takes a few seconds to about 40 seconds and can take up to about 100 seconds, so set your HTTP client’s timeout to about 150 seconds. The turn then keeps running on Google’s side whether or not you are connected. Follow it live with GET /agent/chats/chatId/stream, read it with GET /agent/chats/chatId, or get it posted to your replyUrl when it ends.

A 504 means Google has not confirmed the turn yet, and it may still start. Read the chat with GET /agent/chats/chatId before you send it again.

Each turn uses one captcha, solved by the API with your captcha providers or the free captcha credits of your first account.

https://api.useapi.net/v1/google-flow/agent/chats/chatId/messages

Request Headers 
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
Request Body 
{
  "message": "Now animate @referenceImage_1: the light slowly sweeps across the sea.",
  "referenceImage_1": "user:12345-email:6a6f...-image:9afe71af-38ba-46de-9da3-8f962fae3953"
}

  • message is required, what you say to the agent.
    Maximum length: 20000 characters.

  • referenceImage_1 to referenceImage_7 are optional, images to attach: an id from POST /assets/email, an image made by POST /images, or the referenceId of an image the agent made.
  • referenceVideo_1 is optional, a video to attach: an uploaded video from POST /assets/email, a video made by POST /videos, or the referenceId of a video the agent made.
  • referenceAudio_1 to referenceAudio_5 are optional, voices to attach. Each one is a built-in voice name such as Aoede or Achernar (case-insensitive, the 30 names listed on POST /voices), or a custom voice from POST /voices or GET /voices.
  • character_1 to character_7 are optional, characters from POST /characters or GET /characters.

All references must belong to the account the chat runs on. They can come from any project of that account.

Point at a reference inside the message with an @-mention, the same syntax as POST /videos: @referenceImage_1, @referenceVideo_1, @referenceAudio_1, @character_1. Each @-mention needs its matching parameter. A mentioned reference appears inside the sentence, the way a chip does in the Flow web app. A reference you pass without mentioning it is attached to the message as well.

{
  "message": "Make @character_1 walk into @referenceImage_1 and say hello in the @referenceAudio_1 voice",
  "character_1": "user:12345-email:6a6f...-character:860b2818-...-imgs:2",
  "referenceImage_1": "user:12345-email:6a6f...-image:6bb4a078-...",
  "referenceAudio_1": "Aoede"
}
  • replyUrl is optional, a public https URL that receives one POST with the turn’s result when it ends. When omitted, the replyUrl of your useapi.net account is used, if you set one. The body is described on POST /agent/chats.
  • replyRef is optional, your own reference sent back in the callback body.
    Maximum length: 1024 characters.
  • captchaToken, captchaRetry, captchaOrder are optional, the same captcha parameters as every Flow generation request. See Captcha Parameters.
Responses

  • 202 Accepted

    Google accepted the turn and the agent is working on it.

    {
  "chatId": "c-u12345-email:[email protected]:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow",
  "email": "[email protected]",
  "turn": 2,
  "status": "running"
}

  • 400 Bad Request

    A parameter is missing or invalid, the path value is not a chatId, an @-mention has no matching parameter, or a reference belongs to another account.

    {
  "error": "Parameter message is required",
  "code": 400
}

  • 401 Unauthorized

    Invalid API token.

    {
  "error": "useapi.net ⁝ Unauthorized",
  "code": 401
}

  • 403 Forbidden

    The chatId belongs to another useapi.net user.

    {
  "error": "This chat belongs to another user",
  "code": 403
}

  • 404 Not Found

    The chat was deleted, or its account is not added.

    {
  "error": "Chat not found: it was deleted or never existed",
  "code": 404
}

  • 409 Conflict

    A turn is already running in this chat. Wait for its turn event on the stream, or for the chat’s status to leave running.

    {
  "error": "A turn is already running in this chat. Wait for it to finish",
  "code": 409
}

  • 429 Too Many Requests

    429 has two causes. When the API picked the account itself (no email), retry or pass another account’s email.

    The account already runs 3 agent turns, the most the API runs at once per account. Wait for one to finish, or use another account. The answer carries a Retry-After header (seconds) and a retryAfter time in the body.

    {
  "error": "Account [email protected] already runs 3 agent turns (our limit per account). Wait for one to finish or use another account",
  "code": 429,
  "retryAfter": "2026-10-16T22:26:47.819Z"
}

    The account reached Google’s daily limit on agent messages. Google does not publish the limit. The message Google refused answers with reason AGENT_QUOTA, and after that the API answers at once until midnight UTC, with Retry-After and retryAfter set to that time. Use another account until then.

    {
  "error": "Google's daily Flow agent limit is reached for [email protected]. Try again after 2026-10-17T00:00:00.000Z or use another account",
  "code": 429,
  "retryAfter": "2026-10-17T00:00:00.000Z"
}

  • 502 Bad Gateway

    Google answered with an error or without a readable reply (reason GOOGLE_ERROR or UNREADABLE_ANSWER). The turn may have run. Read the chat with GET /agent/chats/chatId before you send it again.

    {
  "error": "Google answered without a readable reply and may already have run this turn. Check GET /agent/chats/{chatId} before retrying",
  "code": 502,
  "reason": "UNREADABLE_ANSWER",
  "chatId": "c-u12345-email:[email protected]:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow"
}

  • 503 Service Unavailable

    Nothing ran and nothing was charged. Google refused every captcha for the turn (reason CAPTCHA_FAILED), so send the message again. When error starts with Captcha service failed:, the problem is your captcha provider: check its key and balance. When error says Google Flow is not reachable, retry shortly.

    {
  "error": "Google refused every captcha token for this turn. Nothing ran and nothing was charged. Retry",
  "code": 503,
  "reason": "CAPTCHA_FAILED",
  "chatId": "c-u12345-email:[email protected]:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow"
}

    {
  "error": "Google Flow is not reachable right now and could not read the chat. Retry",
  "code": 503
}

  • 504 Gateway Timeout

    Google has not confirmed the turn yet, and it may still start. Read the chat with GET /agent/chats/chatId before you send it again.

    {
  "error": "Google has not confirmed the turn yet; it may still start. Read GET /agent/chats/{chatId} before sending it again",
  "code": 504,
  "chatId": "c-u12345-email:[email protected]:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow",
  "turn": 2
}

  • 596 Session Error

    The account’s Google session is no longer valid. Delete the account with DELETE /accounts/email and add it again by following Setup Google Flow.

Model 
{ // TypeScript, all fields are optional
  chatId: string
  email: string         // the account the chat runs on
  turn: number          // this turn's number
  status: 'running' | 'completed' | 'waiting_approval' | 'failed'  // almost always running
  error?: string        // errors only
  code?: number         // errors only
  reason?: string       // CAPTCHA_FAILED | UNREADABLE_ANSWER | GOOGLE_ERROR | AGENT_QUOTA, on errors after the request reached Google
  retryAfter?: string   // 429 only
}
Examples 
  • CHATID="c-u12345-email:[email protected]:f166200a-...-chat:2a0f1973-...-bot:google-flow"
curl -X POST "https://api.useapi.net/v1/google-flow/agent/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/messages" \
     --max-time 150 \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -d '{ "message": "Make it night time, with stars." }'

  • const token = 'YOUR_API_TOKEN'
const chatId = 'chatId from POST /agent/chats'
const response = await fetch(`https://api.useapi.net/v1/google-flow/agent/chats/${encodeURIComponent(chatId)}/messages`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({ message: 'Make it night time, with stars.' }),
  signal: AbortSignal.timeout(150_000)
})
console.log(response.status, await response.json())

  • import requests
from urllib.parse import quote
token = 'YOUR_API_TOKEN'
chatId = 'chatId from POST /agent/chats'
r = requests.post(
    f'https://api.useapi.net/v1/google-flow/agent/chats/{quote(chatId, safe="")}/messages',
    headers={'Authorization': f'Bearer {token}'},
    json={'message': 'Make it night time, with stars.'},
    timeout=150,
)
print(r.status_code, r.json())
Try It