Generate Videos

November 17, 2025 (November 20, 2026)

Table of contents

  1. Model Capabilities
    1. Models
    2. Aspect ratio (aspectRatio)
    3. Duration (duration, sec)
    4. References
  2. Content Moderation
  3. Why a generation failed
    1. Videos that failed on their sound
  4. Request Headers
  5. Request Body
    1. Core
    2. Account selection
    3. Image references
    4. Characters
    5. Voice narration
    6. Silent videos
    7. Video reference (Omni V2V edit)
    8. Inline @-mention markers (optional)
    9. Async & callbacks
    10. Captcha
  6. Responses
  7. Model
  8. Missing media URLs
    1. How to get the link
  9. Examples
  10. Try It

Generate videos using Google Flow AI models (Omni 1.2 Flash, Omni 1.1 Flash, Veo 3.1 Quality, Veo 3.1 Fast, Veo 3.1 Lite, Veo 3.1 Lite Lower Priority) from text prompts with optional start/end frames, reference images, reference video (Omni V2V edit), and voice narration. Videos are returned as signed URLs ready for download.

Omni 1.2 Flash (omni-flash-1.2) makes clips of any whole number of seconds from 3 to 15, at 360p or 720p, and is the model POST /videos/extend extends with. Google released it on November 5, 2026.

Google is giving Omni 1.2 Flash to accounts over several days from November 5, 2026. Until an account has it, a request for omni-flash-1.2 on that account returns 400 straight away, before any captcha is solved. When the load balancer picks the account (no email), accounts that don’t have the model yet are skipped.

This endpoint features dynamic concurrency management. Video generation typically completes within 60-180 seconds depending on the model and mode. The endpoint automatically polls for completion and returns the final result.

Veo 3.1 Lite Lower Priority is available only to Google AI Ultra $199 subscribers — no credit cost but lower generation priority. The cheaper Ultra $99 plan does not include it. Since 2026-09-23 Google no longer offers it to invited members of an Ultra $199 family plan — only the family manager’s account keeps it. A member account still shows its Ultra credits, but the model is missing from its model list at flow.google.com. The API checks that model list, so a request for this model on a member account returns 400 straight away, before any captcha is solved. When the load balancer picks the account (no email, and no input image, reference, voice or character that ties the request to one account), member accounts are skipped for this model automatically. If Google still refuses the model on an account, the request returns 403 with PUBLIC_ERROR_MODEL_ACCESS_DENIED and the account is skipped for this model for an hour — see Load Balancing Algorithm.

Model Capabilities

Two model families: Veo 3.1 (four variants) and Omni Flash (two versions, Omni 1.2 Flash and Omni 1.1 Flash).

The omni-flash model value is Omni 1.1 Flash, the label the Flow interface has used since Google’s August 26, 2026 update. omni-flash-1.2 is Omni 1.2 Flash, a separate model with its own lengths and prices. The current label of each is shown as displayName on GET /accounts/email.

Models

Veo figures: Google Flow — Credits and pricing. Omni figures measured against the live API.

Omni 1.2 Flash is priced per second, the same on every plan: the first 10 seconds at the base rate and every second past 10 at twice that. An edit costs the same as a generation of the edited length.

Model Generation type(s) Credits per generation
Veo 3.1 - Lite
veo-3.1-lite
4s, 6s, 8s videos Non-Ultra: 10
Ultra: 5
Veo 3.1 - Lite Lower Priority
veo-3.1-lite-low-priority
4s, 6s, 8s videos Ultra $199 only: 0 (lower priority)
Veo 3.1 - Fast (default until 2026-12-05)
veo-3.1-fast
retiring 2026-12-05, then runs as veo-3.1-lite
4s, 6s, 8s videos Non-Ultra: 20
Ultra: 10
Veo 3.1 - Quality
veo-3.1-quality
retiring 2026-12-05, then runs as omni-flash-1.2 at 720p
4s, 6s, 8s videos 100
Omni 1.2 Flash
omni-flash-1.2
3s to 15s videos at 720p
Edit, Extend
Every plan (Free: up to 10s, no extend):
3 per second up to 10s, 6 per second above
3s: 9 · 8s: 24 · 10s: 30 · 15s: 60
Omni 1.2 Flash
omni-flash-1.2 + resolution: 360p
3s to 15s videos at 360p
Edit, Extend
Every plan (Free: up to 10s, no extend):
1 per second up to 10s, 2 per second above
3s: 3 · 8s: 8 · 10s: 10 · 15s: 20
Omni 1.1 Flash
omni-flash
retiring 2026-12-05, then runs as omni-flash-1.2
4s, 6s, 8s, 10s videos at 720p
(does not include edits to uploaded & generated videos)
Plus / Pro / Ultra:
4s: 7
6s: 10
8s: 12
10s: 15
Omni 1.1 Flash
omni-flash + resolution: 360p
retiring 2026-12-05
4s, 6s, 8s, 10s videos at 360p Plus / Pro / Ultra:
4s: 4
6s: 5
8s: 6
10s: 7
Omni 1.1 Flash
omni-flash + referenceVideo_1
retiring 2026-12-05
Edit uploaded & generated videos of all lengths Plus / Pro / Ultra: 20 at 720p, 10 at 360p

Requests for a retiring model keep working after December 5, 2026: from that day a request without model runs as veo-3.1-lite, the new default, and omni-flash at 720p costs about twice the credits (at 360p about the same). The job then shows the model that ran in model.

Aspect ratio (aspectRatio)

Model Supported values
All Veo variants landscape (default), portrait
omni-flash-1.2, omni-flash landscape (default), portrait

Duration (duration, sec)

Mode / Model Supported
Veo T2V / I2V / I2V-FL 4, 6, 8 (default) — 4/6 are Ultra-only
Veo R2V 8 only
omni-flash-1.2 T2V / R2V / I2V any whole number from 3 to 15, 8 (default) — 11 to 15 on paid plans only
omni-flash-1.2 I2V-FL any whole number from 3 to 10, 8 (default)
omni-flash-1.2 V2V edit not accepted — output matches input trim window (max 15 s, set via endFrameIndex_1, max 10 s on a free plan)
omni-flash T2V / R2V / I2V / I2V-FL 4, 6, 8 (default), 10
omni-flash V2V edit not accepted — output matches input trim window (max 10 s, set via endFrameIndex_1)

References

Reference Parameter(s) Veo (all variants) omni-flash-1.2, omni-flash
Start frame (I2V) startImage Yes Yes (the frame only — no referenceImage_*, no character_*, no referenceAudio_*)
Start + end frames (I2V-FL) startImage + endImage Yes Yes (frames only — no referenceImage_*, no character_*, no referenceAudio_*)
Image refs (R2V / Ingredients) referenceImage_1..10 up to 3 (slots _1..3); not on veo-3.1-quality up to 10 on omni-flash-1.2, 7 on omni-flash (R2V) / up to 5 (V2V edit)
Characters (R2V / Ingredients) character_1..10 (from POST /characters) 3 total with referenceImage_* — Veo fast/lite/lite-low-priority only, 8 s only, not on veo-3.1-quality 10 total with referenceImage_* on omni-flash-1.2, 7 on omni-flash (R2V)
Voice narration referenceAudio_1..5 (POST /voices refs OR system voice names) 1 (slot _1, requires an image ref or character, R2V only); not on veo-3.1-quality up to 5 (R2V, requires an image ref or character) / up to 3 (V2V edit)
Source video (V2V edit) referenceVideo_1 (+ optional startFrameIndex_1 / endFrameIndex_1) — Yes (uploaded MP4, trim on a 24 fps virtual timeline, max 360 frames = 15 s on omni-flash-1.2, 240 frames = 10 s on omni-flash)

Content Moderation

If your generation is moderated, retrying with the same prompt often succeeds on subsequent attempts — moderation decisions can vary between requests. Modifying the prompt, removing reference images, or swapping models can also help, as each has different content-moderation behavior.

One case does not improve on retry. IP_PROHIBITED means Google’s intellectual-property classifier flagged an input image as containing copyrighted, branded or recognizable content, and since the image is unchanged a retry gets flagged again. Replace the reference image instead — original photos of non-famous subjects pass where celebrity photos, film stills, product shots and copyrighted characters do not. Despite how it reads, the “IP” here is intellectual property and has nothing to do with network addresses.

Why a generation failed

When every operation in a job fails, the top-level error reads All operations failed for all of them. The reason is in response.failureReasons, a de-duplicated list of everything Google said about the failed media.

Two kinds of string arrive in it, and a job can carry either or both. Terminal codes name what went wrong, and the ones seen most are PUBLIC_ERROR_UNSAFE_GENERATION, PUBLIC_ERROR_PROMINENT_PEOPLE_FILTER_FAILED, PUBLIC_ERROR_AUDIO_FILTERED, PUBLIC_ERROR_MINOR, PUBLIC_ERROR_SEXUAL, PUBLIC_ERROR_DANGER_FILTER, PUBLIC_ERROR_IP_INPUT_IMAGE and, on V2V edits, PUBLIC_ERROR_SPEECH_EDIT. Classifier labels name which filter fired, such as IP_PROHIBITED. The list is Google’s, not ours, so treat it as open-ended and match on substrings rather than on an exhaustive set.

PUBLIC_ERROR_SPEECH_EDIT comes only from V2V edits (referenceVideo_1), and it is the most common named reason there: about a quarter of failed edits carry it. Google refuses the edit because of the speech in the clip and gives no detail beyond the code. The name points at an edit that changes what someone in the video says, so try a prompt that leaves the dialogue as it is, or a source clip without speech.

The field is absent when Google returned no reason at all, which is common enough to code for — around half of V2V edit failures arrive with nothing attached. An absent failureReasons is not an error in itself, and those jobs are usually worth one retry.

A job that failed before any operation started — a rejected request, a moderated prompt — never reaches this path. Those return the Google error verbatim instead, as shown in the 400 responses above.

Videos that failed on their sound

PUBLIC_ERROR_AUDIO_FILTERED, with the label AUDIO_GENERATION_FILTERED, means the picture was fine but Google’s audio filter rejected the sound generated with it. Every model makes sound along with the video, even for a prompt with no dialogue (ambient noise, music, effects), and Google checks that sound separately from the picture. When the filter rejects it, Google fails the whole video by default and charges no credits for it.

It is the most common failure on veo-3.1-lite and the second most common on veo-3.1-lite-low-priority: about 1 in 5 veo-3.1-lite videos and 1 in 12 veo-3.1-lite-low-priority videos fail this way, about 1 in 25 on veo-3.1-fast, and fewer than 1 in 100 on the Omni models.

What you can do:

  • If the video can do without its sound (b-roll, backgrounds, clips you put music or a voice-over on later), send returnSilentVideos: true. Such a video then comes back without sound instead of failing, and Google charges its credits like any other video. This is the “Return silent videos” setting in Google Flow’s own settings, applied per request.
  • If you need the sound, send the request again: each attempt generates new sound, so the filter judges it anew.
  • An Omni model (omni-flash-1.2, omni-flash) hardly ever fails this way.

https://api.useapi.net/v1/google-flow/videos

Request Headers

Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data

Request Body

{
  "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
  "model": "veo-3.1-fast",
  "aspectRatio": "landscape",
  "duration": 8,
  "count": 2
}

Parameters are grouped below. For per-model limits and modes see Model Capabilities above.

Core

  • prompt is required, text description for video generation.
  • model is optional, the AI model to use for video generation (default: veo-3.1-fast, and veo-3.1-lite from December 5, 2026, when Google retires Veo 3.1 Fast). Supported values: omni-flash-1.2, omni-flash, veo-3.1-quality, veo-3.1-fast, veo-3.1-lite, veo-3.1-lite-low-priority. See Model Capabilities.
  • aspectRatio is optional, output video aspect ratio (default: landscape). Supported values: landscape, portrait, for every model.
  • duration is optional, output video length in seconds (default: 8). omni-flash-1.2 takes any whole number from 3 to 15 (3 to 10 with startImage + endImage, and up to 10 on a free Google plan). omni-flash takes 4, 6, 8, 10. Veo takes 4, 6, 8. See Model Capabilities. Not accepted by a V2V edit (output length matches the input trim window).
  • resolution is optional, output resolution (default: 720p). Supported values: 360p, 720p. Omni models only — Veo publishes no 360p variant, so 360p on a Veo model is rejected rather than silently generating 720p at full price. On omni-flash-1.2 a 360p generation costs a third of the same request at 720p, on omni-flash roughly half. A 360p clip can be promoted afterwards with POST /videos/upscale.
  • count is optional, number of video variations to generate (1-4, default: 1).

Account selection

  • email is optional, the Google Flow account to use.

    When only one account is configured, the API will automatically use that account.

    With multiple accounts configured, omitting the email parameter triggers automatic load balancing based on video generation job statistics to select the healthiest account.

    If startImage, endImage, referenceImage_*, or referenceVideo_1 are provided, the email parameter can be omitted — the API will automatically use the same account where the references were uploaded.

Image references

  • startImage is optional, mediaGenerationId from POST /assets/email for I2V mode (video starts with this frame). Supported on Veo and both Omni models, all of which also accept endImage.
  • endImage is optional, mediaGenerationId from POST /assets/email for I2V-FL mode (video ends with this frame, requires startImage). End-frame-only is not supported. On the Omni models the two frames are the only accepted input, so referenceImage_*, character_* and referenceAudio_* are rejected alongside them.
  • referenceImage_1 to referenceImage_10 are optional, mediaGenerationId from POST /assets/email for R2V mode. Slots _1.._3 work on Veo (max 3, not veo-3.1-quality) and both Omni models, slots _4.._7 on the Omni models only, slots _8.._10 on omni-flash-1.2 only. Cannot be combined with startImage/endImage.

Characters

  • character_1 to character_10 are optional, character reference-ids from POST /characters. Triggers R2V (Ingredients) mode just like referenceImage_* does. Each character’s image count rolls into the model’s image-ref budget (see Model Capabilities › References):
    • Veo 3.1 Fast / Lite / Lite Lower Priority (veo-3.1-fast, veo-3.1-lite, veo-3.1-lite-low-priority) — characters supported in 8 s only; referenceImages.length + Σ(character.imgs) ≤ 3.
    • Omni 1.2 Flash and Omni 1.1 Flash (omni-flash-1.2, omni-flash) — characters supported in all durations. referenceImages.length + Σ(character.imgs) ≤ 10 on omni-flash-1.2, ≤ 7 on omni-flash.
    • Veo 3.1 Quality (veo-3.1-quality) — characters NOT supported (no Ingredients mode).

Voice narration

  • referenceAudio_1 to referenceAudio_5 are optional. Each slot accepts either a system voice name (case-insensitive, one of the 30 presets) or a user voice from POST /voices. Per-model limits are in the References table above.

System voice presets (30 names):

[
  "Achird", "Achernar", "Algieba", "Algenib", "Alnilam",
  "Aoede", "Autonoe", "Callirrhoe", "Charon", "Despina",
  "Enceladus", "Erinome", "Fenrir", "Gacrux", "Iapetus",
  "Kore", "Laomedeia", "Leda", "Orus", "Puck",
  "Pulcherrima", "Rasalgethi", "Sadachbia", "Sadaltager", "Schedar",
  "Sulafat", "Umbriel", "Vindemiatrix", "Zephyr", "Zubenelgenubi"
]

System voice samples: https://www.gstatic.com/aitestkitchen/voices/samples/{Name}.wav

To list user (custom) voices on an account: GET /voices?email=…&source=user. To preview a single voice (system or user): GET /voices/ref.

Silent videos

  • returnSilentVideos is optional (default: false). Every model generates sound with the video, and Google checks that sound with its own audio filter. When the filter rejects it, false fails the video with PUBLIC_ERROR_AUDIO_FILTERED and Google charges nothing for it. true returns the video without sound, charged like any other video. It is the same as “Return silent videos” in Google Flow’s settings, applied to this request only, whatever the account’s own setting says. See Videos that failed on their sound.

Video reference (Omni V2V edit)

  • referenceVideo_1 is optional (Omni models only), mediaGenerationId of a video uploaded via POST /assets/email, or of a video this API generated or edited earlier. Switches the request into V2V edit mode. Cannot be combined with startImage/endImage.
  • startFrameIndex_1 is optional (Omni V2V only, paired with referenceVideo_1), trim start on a 24 fps virtual timeline. Range: 0-359 on omni-flash-1.2, 0-239 on omni-flash. Default: 0.
  • endFrameIndex_1 is optional (Omni V2V only, paired with referenceVideo_1), trim end on a 24 fps virtual timeline. Range: 1-360 on omni-flash-1.2 (360 = 15 s), 1-240 on omni-flash (240 = 10 s). Default: the end of the clip, or the model’s maximum for longer clips. Must be greater than startFrameIndex_1. On a free Google plan an omni-flash-1.2 edit covers at most 10 s (240 frames).

An edit works on a slice of the input video, and startFrameIndex_1 / endFrameIndex_1 pick that slice. Google counts 24 frames per second, so frame 24 is one second in, frame 120 is five seconds in, and frame 240 is ten seconds in. The output is that slice re-rendered with your edit, so it is exactly as long as the slice. There is no duration parameter on an edit. On omni-flash-1.2 an edit costs the same as a generation of the slice’s length (a 3 s slice at 360p costs 3 credits).

The table shows omni-flash. On omni-flash-1.2 the same rules hold with a 15 s (360 frame) maximum, so a 13 s clip is edited whole.

Input clip You send Slice used Output
10 s nothing frames 0 to 240 10 s
10 s endFrameIndex_1: 120 frames 0 to 120 5 s
13 s nothing frames 0 to 240 10 s, the last 3 s of the input are not used
8 s nothing frames 0 to 192 8 s

An edit does not add time to a video. The motion follows the source closely: in our tests the edit reproduced the source’s first and last frames almost exactly, and a prompt asking it to begin elsewhere was ignored. Feeding the output back in as the next referenceVideo_1 with a new line to say gives you a new take of the same seconds, with the voice and the gestures carried over from the source.

To make a clip longer, use POST /videos/extend, which adds up to 10 seconds at a time with Omni 1.2 Flash and returns one continuous clip. Chaining edits is the other way to get a longer piece out of an Omni clip, and the joins can be made invisible with one precaution at the start. Because every edit opens and closes on the same frames as its source, the only thing that shows at a join is the difference between the source’s own first and last frame. Remove it at the seed: generate a still of the presenter at rest with POST /images, make the first clip with that still as both startImage and endImage, and every edit chained from it opens and closes on that same frame. Join the run with POST /videos/concatenate and the cuts land still-to-still. The quiet beat that pins each clip to the still also shows at a join as a hold, about half a second before the presenter speaks and a third of a second of settling after, so trim it there: roughly trimEnd: 0.375 on every clip but the last and trimStart: 0.458 on every clip but the first leaves two frames of rest across each cut. Measured on a 4-second talking head, the joins were then indistinguishable from the motion inside the clips and the longest hold was an eighth of a second.

Google’s V2V moderation is non-deterministic. The exact same body can land on a content-safety reject (IDENTIFIABLE_PERSON_SAFETY, CHILD_SAFETY, etc.) on one attempt and a clean success on the next. A simple resubmit usually clears it — no input changes needed.

Inline @-mention markers (optional)

You can place @-markers inside prompt that resolve to the body parameters you supply. Markers are case-insensitive and opt-in — a prompt with no markers behaves exactly like before.

Supported markers (one per body slot):

Marker Resolves to
@character_1..10 matching character_N body param
@referenceImage_1..10 matching referenceImage_N body param
@referenceAudio_1..5 matching referenceAudio_N body param
@referenceVideo_* NOT supported inline — pass referenceVideo_1 as a body field. The API returns 400 if it appears in prompt.

Rules:

  • Each marker MUST have a matching body slot supplied. Otherwise the API returns 400 with 'character_N' was not provided in the request body.
  • A slot referenced inline still goes into the upstream reference array — markers are positional/grounding info, not a replacement for the body params.
  • Same slot may be inlined multiple times in one prompt; the upstream reference array de-duplicates by id.
  • Body params supplied but NOT inlined still flow to the upstream reference array (unchanged behavior).
  • Unknown strings like @gmail.com or @anyword_1 (no _<digit> after a recognized slot name) pass through as literal prompt text.

Example:

{
  "model": "omni-flash",
  "prompt": "@character_1 sitting on @referenceImage_1, @character_2 standing beside, @referenceImage_2 visible in the background, smooth camera dolly",
  "character_1":       "user:123-email:...-character:...-imgs:1",
  "character_2":       "user:123-email:...-character:...-imgs:1",
  "referenceImage_1":  "user:123-email:...-image:...",
  "referenceImage_2":  "user:123-email:...-image:..."
}

Async & callbacks

  • async is optional, enables fire-and-forget mode (default: false). When true, returns immediately with 201 Created and job metadata. Poll GET /jobs/jobId for completion status. Useful for avoiding long request timeouts since video generation takes 60-180 seconds.
  • replyUrl is optional, webhook URL for job status callbacks. Receives POST requests with job status updates (created, started, completed, failed). The JSON payload shape matches GET /jobs/jobId response.
  • replyRef is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end.

Captcha

  • captchaToken, captchaRetry, captchaOrder are optional, mutually exclusive captcha parameters. See Captcha Parameters for details.

Responses

  • 200 OK

    Videos generated successfully. All video data is in the media[] array.

    {
      "jobId": "j1117123456789304152v-u12345-email:john@gmail.com-bot:google-flow",
      "operations": [],
      "media": [
        {
          "name": "a1d95d21-75d2-482d-a354-14ef8802ce66",
          "projectId": "9f63078c-...redacted...",
          "workflowId": "fa986834-...redacted...",
          "workflowStepId": "CAE",
          "mediaMetadata": {
            "createTime": "2026-11-15T23:14:02.931677Z",
            "mediaTitle": "A serene mountain landscape at sunset with camera slowly panning right",
            "mediaBlobSize": "6895556",
            "mediaStatus": {
              "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_SUCCESSFUL"
            },
            "visibility": "PRIVATE",
            "requestData": {
              "videoGenerationRequestData": {
                "backend": "flow",
                "statusEnum": 3,
                "aspectEnum": 2,
                "videoModelControlInput": {
                  "videoModelName": "veo_3_1_t2v_fast",
                  "videoGenerationMode": "VIDEO_GENERATION_MODE_TEXT_TO_VIDEO",
                  "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
                  "videoResolution": "VIDEO_RESOLUTION_720P"
                }
              },
              "promptInputs": [
                {
                  "structuredPrompt": {
                    "parts": [
                      { "text": "A serene mountain landscape at sunset with camera slowly panning right" }
                    ]
                  }
                }
              ],
              "clientPlatform": "CLIENT_PLATFORM_WEB"
            }
          },
          "video": {
            "generatedVideo": {
              "seed": 123456,
              "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
              "model": "veo_3_1_t2v_fast",
              "baseImageMediaGenerationId": "",
              "isLooped": false,
              "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE"
            },
            "dimensions": { "length": "8s" },
            "operation": {
              "name": "a1d95d21-75d2-482d-a354-14ef8802ce66"
            }
          },
          "videoUrl": "https://flow-content.google/video/a1d95d21-...redacted...?Expires=...",
          "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...redacted...?Expires=...",
          "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-75d2-482d-a354-14ef8802ce66"
        }
      ],
      "remainingCredits": 18760,
      "captcha": {
        "service": "AntiCaptcha",
        "taskId": "931846120",
        "durationMs": 15243,
        "attempts": [
          {
            "service": "AntiCaptcha",
            "success": true,
            "durationMs": 15243,
            "cost": "0.00200",
            "ip": "203.0.113.24",
            "createTime": 1794787642,
            "endTime": 1794787657,
            "solveCount": 0,
            "taskId": "931846120",
            "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.0.0 Safari/537.36"
          }
        ]
      }
    }
    
  • 201 Created

    Job created in async mode (async: true). Video generation is processing in the background.

    Use GET /jobs/jobId to poll for completion status.

    {
      "jobid": "j1117123456789304152v-u12345-email:john@gmail.com-bot:google-flow",
      "type": "video",
      "status": "created",
      "created": "2025-11-17T12:34:56.789Z",
      "request": {
        "email": "john@gmail.com",
        "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
        "model": "veo-3.1-fast",
        "aspectRatio": "landscape",
        "duration": 8,
        "count": 2,
        "async": true,
        "replyUrl": "https://your-domain.com/webhook",
        "replyRef": "custom-reference-123"
      },
      "response": {
        "operations": [],
        "media": [
          {
            "name": "1450903d-...redacted...-9c86f0",
            "projectId": "9f63078c-...redacted...",
            "workflowId": "b3e1c0de-...redacted...",
            "workflowStepId": "CAE",
            "mediaMetadata": {
              "createTime": "2025-11-17T12:34:58.102934Z",
              "mediaTitle": "A serene mountain landscape at sunset with camera slowly panning right",
              "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_PENDING" },
              "visibility": "PRIVATE",
              "requestData": {
                "videoGenerationRequestData": {
                  "backend": "flow",
                  "statusEnum": 6,
                  "aspectEnum": 2,
                  "videoModelControlInput": {
                    "videoModelName": "veo_3_1_t2v_fast",
                    "videoGenerationMode": "VIDEO_GENERATION_MODE_TEXT_TO_VIDEO",
                    "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
                    "videoResolution": "VIDEO_RESOLUTION_720P"
                  }
                },
                "promptInputs": [
                  { "structuredPrompt": { "parts": [{ "text": "A serene mountain landscape at sunset with camera slowly panning right" }] } }
                ],
                "clientPlatform": "CLIENT_PLATFORM_WEB"
              }
            },
            "video": {
              "generatedVideo": {
                "seed": 527083,
                "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
                "model": "veo_3_1_t2v_fast",
                "baseImageMediaGenerationId": "",
                "isLooped": false,
                "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE"
              },
              "dimensions": { "length": "8s" },
              "operation": { "name": "1450903d-...redacted...-9c86f0" }
            }
          },
          {
            "name": "f2eec9bd-...redacted...-e16f7a",
            "projectId": "9f63078c-...redacted...",
            "workflowId": "c47a90b1-...redacted...",
            "workflowStepId": "CAE",
            "mediaMetadata": {
              "createTime": "2025-11-17T12:34:58.102934Z",
              "mediaTitle": "A serene mountain landscape at sunset with camera slowly panning right",
              "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_PENDING" },
              "visibility": "PRIVATE",
              "requestData": {
                "videoGenerationRequestData": {
                  "backend": "flow",
                  "statusEnum": 6,
                  "aspectEnum": 2,
                  "videoModelControlInput": {
                    "videoModelName": "veo_3_1_t2v_fast",
                    "videoGenerationMode": "VIDEO_GENERATION_MODE_TEXT_TO_VIDEO",
                    "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
                    "videoResolution": "VIDEO_RESOLUTION_720P"
                  }
                },
                "promptInputs": [
                  { "structuredPrompt": { "parts": [{ "text": "A serene mountain landscape at sunset with camera slowly panning right" }] } }
                ],
                "clientPlatform": "CLIENT_PLATFORM_WEB"
              }
            },
            "video": {
              "generatedVideo": {
                "seed": 81946,
                "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
                "model": "veo_3_1_t2v_fast",
                "baseImageMediaGenerationId": "",
                "isLooped": false,
                "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE"
              },
              "dimensions": { "length": "8s" },
              "operation": { "name": "f2eec9bd-...redacted...-e16f7a" }
            }
          }
        ],
        "captcha": {
          "service": "CapSolver",
          "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e",
          "durationMs": 5357,
          "attempts": [
            {
              "service": "CapSolver",
              "success": true,
              "durationMs": 5357,
              "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e",
              "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.0.0 Safari/537.36",
              "secChUa": "\"Google Chrome\";v=\"153\", \"Not_A Brand\";v=\"8\", \"Chromium\";v=\"153\""
            }
          ]
        },
        "captchaAttemptsCount": 1,
        "captchaProviders": "CapSolver",
        "tier": "PAYGATE_TIER_TWO",
        "sku": "G1_TIER2",
        "remainingCredits": 24235
      }
    }
    
  • 400 Bad Request

    Invalid request (validation error, mode conflict, email mismatch, or content policy violation).

    Validation error:

    {
      "error": "Model 'veo-3.1-quality' does not support R2V mode (MULTI_REFERENCE_NO_STYLE)",
      "code": 400
    }
    

    Model not offered on this account (veo-3.1-lite-low-priority on an invited member of an Ultra $199 family plan, answered before any captcha is solved):

    {
      "error": "Google no longer offers veo-3.1-lite-low-priority on this account (user@gmail.com). Since 2026-09-23 invited members of a Google AI Ultra $199 family plan do not have it — only the family manager's account keeps it. Use an account that still lists it at flow.google.com, or another model.",
      "code": 400
    }
    

    Content policy error:

    {
      "jobId": "j1117123456789304152v-u12345-email:john@gmail.com-bot:google-flow",
      "error": "PUBLIC_ERROR_UNSAFE_GENERATION (HTTP 400)",
      "code": 400,
      "response": {
        "error": {
          "code": 400,
          "message": "flow.google.com YhhmEf failed",
          "status": "INVALID_ARGUMENT",
          "details": [
            {
              "@type": "type.googleapis.com/google.rpc.ErrorInfo",
              "reason": "PUBLIC_ERROR_UNSAFE_GENERATION"
            }
          ]
        },
        "captcha": {
          "service": "CapSolver",
          "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e",
          "durationMs": 5357,
          "attempts": [
            {
              "service": "CapSolver",
              "success": true,
              "durationMs": 5357,
              "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e"
            }
          ]
        }
      }
    }
    

    All operations failed (during polling):

    The top-level error is always the same sentence, so the reason is in response.failureReasons — see Why a generation failed above. Each video in response.media also carries its own reason (shortened here to the fields that matter).

    {
      "jobId": "j1117123456789304152v-u12345-email:john@gmail.com-bot:google-flow",
      "error": "All operations failed",
      "code": 400,
      "response": {
        "operations": [],
        "media": [
          {
            "name": "a629a9...redacted",
            "projectId": "9f63078c-...redacted...",
            "mediaMetadata": {
              "mediaStatus": {
                "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_FAILED",
                "error": {
                  "code": 3,
                  "message": "PUBLIC_ERROR_MINOR"
                }
              },
              "requestData": {
                "videoGenerationRequestData": { "backend": "flow", "statusEnum": 4, "aspectEnum": 2 }
              }
            },
            "video": {
              "operation": { "name": "a629a9...redacted" }
            },
            "mediaGenerationId": "user:12345-email:6a6f...-video:a629a9...redacted"
          }
        ],
        "remainingCredits": 18760,
        "failureReasons": [
          "PUBLIC_ERROR_MINOR"
        ],
        "captcha": {
          "service": "CapSolver",
          "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e",
          "durationMs": 5357,
          "attempts": [
            {
              "service": "CapSolver",
              "success": true,
              "durationMs": 5357,
              "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e"
            }
          ]
        }
      }
    }
    
  • 401 Unauthorized

    Invalid API token.

    {
      "error": "useapi.net ⁝ Unauthorized",
      "code": 401
    }
    
  • 402 Payment Required

    Subscription expired or insufficient credits.

    {
      "error": "useapi.net ⁝ Your account has no subscription, please subscribe to our services before submitting requests",
      "code": 402
    }
    
  • 403 Forbidden

    Google rejected the captcha on every try. We retry with a fresh captcha as many times as you allow (captchaRetry, default 5, or the providers in captchaOrder) and return this 403 only when all of them were rejected. The top-level error starts with captcha_quality:, for example "captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY after 5 attempts. Google refused all 5 captcha tokens for user@example.com, so nothing was generated and no Google Flow credits were used (5 captcha solves were spent). Google is flagging this account's requests as unusual activity. If it keeps happening, use another account, or leave out email so the API picks one. See GET /accounts/captcha-stats summary.by_account". A 429 with PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC reads the same way.

    Two 403s are not a captcha problem, and we answer them after one try instead of retrying. PUBLIC_ERROR_MODEL_ACCESS_DENIED in the response means Google refused the model on that account, so raising captchaRetry or adding providers will not help. Check that the account’s plan includes the model. Since 2026-09-23 Google no longer offers veo-3.1-lite-low-priority to invited members of an Ultra $199 family plan — only the family manager’s account keeps it.

    PUBLIC_ERROR_USER_MINOR means Google treats the Google account as belonging to someone under 18, and Google Flow is not available to such accounts. The error says so in plain words. No captcha or retry changes it: use another Google account, or have this one’s age verified with Google first. With email omitted, the load balancer sets such an account aside for 1 hour, then tries it again.

    Nothing was created when this happens. Google checks the captcha before it starts generating, so no Google credits were used and you can resubmit straight away. Your captcha provider still bills each solve.

    The usual cause is the Google account, not the captcha provider. Google gives each account its own trust level. On a trusted account it accepts about 9 in 10 captchas, on a distrusted one about 3 in 10, whichever provider solved them. Most customers have a few distrusted accounts among many good ones.

    To see which accounts are affected, use GET /accounts/captcha-stats. Its summary.by_account shows, for each of your Google accounts, how many captchas were tried and what share Google accepted. GET account/stats with bot=google-flow also shows how many requests each account finished with each response code.

    • If one or a few accounts are far below the others, the API already sends them less work: when you leave out email, each captcha Google rejected on an account in the last 15 minutes lowers its chance of being picked, for generations and for image uploads. They still get some work, so an account that recovers gets its full share back. If you pin requests with email, move them to your other accounts yourself. Replace an account that stays low for more than a day or two.
    • If all your accounts drop at the same time, it’s the captcha provider. Configure at least two providers with POST /accounts/captcha-providers, and the API will start with whichever one Google accepts best.

    A higher captchaRetry gets more requests through on a distrusted account, but every extra try is another paid solve.

  • 404 Not Found

    Account not found or not configured.

    {
      "error": "Google Flow account john@gmail.com not found",
      "code": 404
    }
    
  • 408 Request Timeout

    Video generation polling timeout (after 10 minutes).

    {
      "error": "Video generation polling timeout after 120 attempts (600s)",
      "code": 408
    }
    
  • 429 Too Many Requests

    Google returns several RESOURCE_EXHAUSTED 429 variants. Check the reason field and respond accordingly:

    Reason Meaning Scope What to do Cooldown
    PUBLIC_ERROR_
    USER_REQUESTS_THROTTLED
    Google is throttling the account (the token was fine). Uploads and generation are metered separately All models on the account — or uploads only, when POST /assets triggered it Run fewer parallel requests, or switch accounts. From POST /assets, retrying the same one rarely clears it ~30 min. From POST /assets, treat it as a minimum — it can persist
    PUBLIC_ERROR_
    USER_QUOTA_REACHED
    Account’s overall Flow quota cap All models on the account Add accounts, or omit email to load-balance ~30 min
    PUBLIC_ERROR_
    PER_MODEL_DAILY_QUOTA_REACHED
    Per-model daily quota Only that model, on that account Switch model, or wait Next UTC midnight
    PUBLIC_ERROR_
    UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC
    Google rejected the captcha on every try (we already retried). Usually a distrusted Google account, sometimes the provider Per request Check which accounts are affected in captcha-stats. Rest or replace those accounts. Add a second provider if all accounts drop together 60s

    Every 429 returns the cooldown two ways — an HTTP Retry-After: <seconds> header and a body retryAfter: <ISO timestamp> field. Honor it before retrying.

    When email is omitted, the first three reasons quarantine the account and the load balancer routes around it. If every account is quarantined for the model you get 429 with error: "no_eligible_account". Routing details: GET /jobs › Load Balancing Algorithm.

    Captcha-quality failures prefix the top-level error with captcha_quality: (e.g. "captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC after 3 attempts") so you can detect them without parsing the nested body.

  • 503 Service Unavailable

    503 has two distinct causes — check the response body to tell them apart.

    A transient Google-side outage. Wait 5-10 seconds and retry.

    {
      "error": {
        "code": 503,
        "message": "Service temporarily unavailable.",
        "status": "UNAVAILABLE"
      }
    }
    

    A captcha-provider failure — the top-level error is prefixed Captcha service failed:. The problem is your captcha provider (check its API key and balance), not Google. Don’t retry until the provider is back.

    {
      "error": "Captcha service failed: ERROR_ZERO_BALANCE",
      "code": 503
    }
    
  • 596 Session Error

    Google rejected the account’s session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering 596 and you get a reconnect email: add it again by following Setup Google Flow.

    {
      "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.",
      "code": 596
    }
    

Model

One tab per answer: the finished videos (200, sync), the job record (201, async) and a failed job.

The answer for each status, field by field, and the types it uses (FlowVideoMedia, FlowCaptcha, FlowReference)
  • Video generation completed. Returns full video data with signed URLs. FlowVideoMedia and FlowCaptcha are described below the tabs.

    {
      jobId: string                              // the job id, for GET /jobs/{jobid}
      operations: []                             // always empty, kept for older clients: read media[]
      media: FlowVideoMedia[]                    // one item per video
      remainingCredits?: number                  // the account's Google Flow credits left, as Google last reported them
      captcha: FlowCaptcha                       // the captcha solved for this request
    }
    
  • Job created and processing in background. Structure matches GET /jobs/jobId response. References you sent come back decoded, as FlowReference objects (described below the tabs).

    {
      jobid: string                              // the job id, for GET /jobs/{jobid}
      type: 'video'                              // the job type
      status: 'created'                          // the job status
      created: string                            // ISO 8601 time the job was created
      request: {                                 // the request as you sent it, after validation
        email: string                            // the account the job runs on (the one you named, or the one the API picked)
        prompt: string                           // the prompt
        model?: string                           // the model you asked for
        aspectRatio?: string                     // the aspect ratio you asked for
        duration?: number                        // the length you asked for, in seconds
        resolution?: string                      // the resolution you asked for
        count?: number                           // how many videos you asked for
        startImage?: FlowReference               // the first-frame image
        endImage?: FlowReference                 // the last-frame image
        referenceImage_1?: FlowReference         // a reference image
        referenceImage_2?: FlowReference         // a reference image
        referenceImage_3?: FlowReference         // a reference image
        referenceImage_4?: FlowReference         // a reference image
        referenceImage_5?: FlowReference         // a reference image
        referenceImage_6?: FlowReference         // a reference image
        referenceImage_7?: FlowReference         // a reference image
        referenceImage_8?: FlowReference         // a reference image
        referenceImage_9?: FlowReference         // a reference image
        referenceImage_10?: FlowReference        // a reference image
        character_1?: FlowReference              // a character
        character_2?: FlowReference              // a character
        character_3?: FlowReference              // a character
        character_4?: FlowReference              // a character
        character_5?: FlowReference              // a character
        character_6?: FlowReference              // a character
        character_7?: FlowReference              // a character
        character_8?: FlowReference              // a character
        character_9?: FlowReference              // a character
        character_10?: FlowReference             // a character
        referenceAudio_1?: string                // a voice: a built-in voice name (lowercase) or your voice reference
        referenceAudio_2?: string                // a voice: a built-in voice name (lowercase) or your voice reference
        referenceAudio_3?: string                // a voice: a built-in voice name (lowercase) or your voice reference
        referenceAudio_4?: string                // a voice: a built-in voice name (lowercase) or your voice reference
        referenceAudio_5?: string                // a voice: a built-in voice name (lowercase) or your voice reference
        referenceVideo_1?: FlowReference         // the video to edit
        startFrameIndex_1?: number               // the first frame of the video to edit
        endFrameIndex_1?: number                 // the last frame of the video to edit
        returnSilentVideos?: boolean             // true: a video whose sound Google's filter rejects comes back silent
        captchaToken?: string                    // the captcha token you sent
        captchaRetry?: number                    // the captcha retries you asked for
        captchaOrder?: string[]                  // the captcha providers you listed, in order
        async: true                              // answer at once, the job runs in the background
        replyUrl?: string                        // your callback URL
        replyRef?: string                        // your reference, sent back in callbacks
      }
      model?: string                             // the model that ran, only when it is not the one you asked for (a retired model, routed to its replacement)
      response: {                                // Google's answer so far
        operations: []                           // always empty, kept for older clients: read media[]
        media: FlowVideoMedia[]                  // one item per video, still being made (no mediaGenerationId or URLs yet)
        captcha: FlowCaptcha                     // the captcha solved for this request
        captchaAttemptsCount: number             // how many captcha solves were tried, one per entry of captcha.attempts
        captchaProviders: string                 // the providers tried, comma-separated, in the order tried
        tier: string                             // the account's Google plan tier when the job started, as Google reports it, e.g. "PAYGATE_TIER_TWO"
        sku: string                              // the account's Google plan code when the job started, e.g. "G1_TIER2"
        remainingCredits?: number                // the account's Google Flow credits left, as Google reported them at submit
      }
    }
    
  • Error response structure (applies to both sync and async modes).

    {
      jobId?: string                             // the job id, when the job had been created
      error: string                              // what went wrong, e.g. "All operations failed" or "PUBLIC_ERROR_UNSAFE_GENERATION (HTTP 400)"
      code?: number                              // the HTTP status
      retryAfter?: string                        // ISO 8601 time to retry after, on a 429 (the Retry-After header carries the same in seconds)
      response?: {                               // what the job held when it failed
        failureReasons?: string[]                // why every video failed: Google's terminal codes and classifier labels, de-duplicated,
                                                 // e.g. PUBLIC_ERROR_IP_INPUT_IMAGE or IP_PROHIBITED. Present only when all videos
                                                 // failed and Google gave a reason
        operations?: []                          // always empty, kept for older clients
        media?: FlowVideoMedia[]                 // every video of the job, when none was made: each carries its own reason in mediaMetadata.mediaStatus
        remainingCredits?: number                // the account's Google Flow credits left, as Google last reported them
        error?: string | {                       // Google's error when Google refused the request, or our own text (e.g. a polling timeout)
          code: number                           // HTTP status Google answered
          message: string                        // the error message, e.g. "flow.google.com YhhmEf failed"
          status: string                         // Google's status name, e.g. "RESOURCE_EXHAUSTED"
          details: Array<{                       // Google's error details
            '@type': string                      // the type name of the detail
            reason: string                       // Google's reason code, e.g. "PUBLIC_ERROR_USER_QUOTA_REACHED"
          }>
        }
        captcha?: FlowCaptcha                    // the captcha tried or used
        captchaAttemptsCount?: number            // how many captcha solves were tried, when the job failed before its first poll
        captchaProviders?: string                // the providers tried, comma-separated, when the job failed before its first poll
        tier?: string                            // the account's Google plan tier, when the job failed before its first poll
        sku?: string                             // the account's Google plan code, when the job failed before its first poll
      }
      message?: string                           // on the load-balancer 429 only (error no_eligible_account: every account is quarantined for this model): the explanation
      skipReasons?: Array<{                      // on the load-balancer 429 only: why each account was left out
        email: string                            // the account left out
        reason: string                           // Google reason that triggered the quarantine (a 429 reason, or the MODEL_ACCESS_DENIED or USER_MINOR 403)
        model: string                            // Quarantined model, or "*" for account-wide
      }>
    }
    

The types the tabs refer to:

FlowVideoMedia: each item of media in the tabs above.

{
  name: string                               // Google's media id of the video
  projectId: string                          // the Google Flow project the video is in
  workflowId?: string                        // the Google Flow workflow (project item) that holds the video
  workflowStepId?: string                    // the workflow step, e.g. "CAE" (left out when Google's record has none)
  mediaMetadata: {                           // Google's record of the video
    createTime?: string                      // ISO 8601 time Google created the video
    mediaTitle?: string                      // the prompt, as Google Flow titles the video (an upscale has none)
    mediaBlobSize?: string                   // the MP4's size in bytes, as a string, once the video is done
    mediaStatus: {                           // whether the video was made
      mediaGenerationStatus: string          // MEDIA_GENERATION_STATUS_PENDING | MEDIA_GENERATION_STATUS_ACTIVE |
                                             // MEDIA_GENERATION_STATUS_SUCCESSFUL | MEDIA_GENERATION_STATUS_FAILED |
                                             // MEDIA_GENERATION_STATUS_UNKNOWN
      error?: {                              // why the video failed
        code: number                         // Google's error code
        message: string                      // Google's reason, e.g. "PUBLIC_ERROR_IP_INPUT_IMAGE"
      }
      failureReasons?: string[]              // Google's classifier labels for a failed video, e.g. "IP_PROHIBITED"
    }
    visibility?: string                      // "PRIVATE" (left out on a failed video)
    requestData: {                           // what the video was made from, as Google echoes it
      videoGenerationRequestData: {          // the generation settings
        backend: 'flow'                      // the video was made on `flow.google.com`
        statusEnum: number | null            // Google's raw status number: 6 queued, 1 and 2 running, 3 done, 4, 5 and 7 failed
        aspectEnum: number | null            // Google's raw aspect number: 2 landscape, 1 portrait
        videoModelControlInput?: {           // the model settings Google ran
          videoModelName?: string            // Google's own key for the model that ran
          videoGenerationMode?: string       // VIDEO_GENERATION_MODE_TEXT_TO_VIDEO | VIDEO_GENERATION_MODE_REFERENCE_TO_VIDEO |
                                             // VIDEO_GENERATION_MODE_VIDEO_EXTENSION (left out for the other modes)
          videoAspectRatio?: string          // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT
          videoResolution?: string           // VIDEO_RESOLUTION_360P | VIDEO_RESOLUTION_720P | VIDEO_RESOLUTION_1080P |
                                             // VIDEO_RESOLUTION_4K
        }
      }
      promptInputs?: Array<{                 // the prompt as Google received it (an upscale has none)
        structuredPrompt: {                  // the prompt in parts
          parts: Array<{                     // a run of text, or an @-mention
            text?: string                    // a run of prompt text
            reference?: object               // an @-mention: { media: { mediaId, handle } }, { audio: { mediaId, handle } } or { entity: { entityId, handle } }
          }>
        }
      }>
      clientPlatform?: string                // "CLIENT_PLATFORM_WEB"
    }
  }
  video: {                                   // the video's details
    generatedVideo?: {                       // how Google made it (left out until Google reports it)
      seed: number                           // the seed Google used (0 when it reports none)
      prompt: string                         // the prompt as Google ran it (Veo rewrites it), an empty string on an upscale
      model: string                          // Google's own key for the model that ran
      baseImageMediaGenerationId?: string    // an empty string on every video so far
      isLooped: false                        // always false
      aspectRatio: string                    // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT
                                             // (an empty string when Google reports none)
      upsampleMetadata?: {                   // on an upscaled video
        videoUpsampleResolution: string      // VIDEO_UPSAMPLE_RESOLUTION_720P | VIDEO_UPSAMPLE_RESOLUTION_1080P
                                             // (left out for 4K)
      }
    }
    dimensions?: {                           // the clip's measurements (an upscaled clip has none)
      length: string                         // the clip's length, e.g. "8s"
    }
    operation: {                             // the generation operation
      name: string                           // the same as name
    }
  }
  mediaGenerationId?: string                 // the id to pass to the other endpoints (upscale, extend, GIF, concatenate, assets), on every finished answer, left out of the 201 answer
  videoUrl?: string                          // signed MP4 download URL, valid about 6 hours, once the video is done
  thumbnailUrl?: string                      // signed JPEG thumbnail URL, valid about 6 hours
}

FlowCaptcha: the captcha in the tabs above.

{
  service?: string                           // the provider whose token Google accepted: `CapSolver`, `AntiCaptcha`,
                                             // `YesCaptcha`, `CapMonster`, `SolveCaptcha`, `2Captcha`, `EzCaptcha` or
                                             // `UserProvided`. Always on a success answer
  taskId?: string                            // that provider's task id (none for `UserProvided`)
  durationMs?: number                        // ms from the first solve to the token used. Always on a success answer
  error?: string                             // why no captcha token could be had, on a failed request
  attempts: Array<{                          // every solve tried, in order, failed ones included
    service: string                          // the provider asked
    taskId?: string                          // that provider's task id
    durationMs: number                       // how long this solve took, in ms
    success: boolean                         // true when the provider returned a token (Google may still have refused it)
    error?: string                           // why the solve failed
    userAgent?: string                       // the browser user agent the provider solved with, when it reports one
    secChUa?: string                         // the Sec-CH-UA value the provider solved with, when it reports one (may be empty)
    cost?: string                            // the provider's price for this solve, as the provider reports it
    ip?: string                              // the IP address the provider reports for this solve
    createTime?: number                      // Unix time the provider started the solve, as it reports it
    endTime?: number                         // Unix time the provider finished the solve, as it reports it
    solveCount?: number                      // the provider's own solve counter for this task
  }>
}

FlowReference: each image, character or video reference in request above.

{
  user: number                               // your useapi.net user id, read from the reference
  email: string                              // the Google account the media belongs to, read from the reference
  type: 'image' | 'video' | 'character'      // what the reference points to
  id: string                                 // Google's media id (image or video), or the character's entity id
  referenceId: string                        // the reference you sent
  meta?: {                                   // characters only
    imgs: number                             // how many images the character holds (they count toward the model's image limit)
    voiceWorkflowId?: string                 // the voice attached to the character, when it has one
  }
}

Missing media URLs

Media URL fields are optional and can be absent even when generation succeeded. When videoUrl, thumbnailUrl, fifeUrl, servingBaseUri, previewUrl or audioUrl is missing, the media itself is fine — only the download link could not be produced at that moment.

This is rare. Across the seven days of request logs we keep, it happened on one day only — twice, for about four hours and about forty minutes — and not at all on the other six. Google issues those links from an endpoint that limits how often it will answer a given network address, so it is Google limiting our outbound calls rather than useapi.net limiting you, and nothing you do triggers it. While it lasts it affects every account generating at that moment, then clears on its own. Your generation still completed and was charged as usual.

On a media item that generated successfully — mediaStatus.mediaGenerationStatus is MEDIA_GENERATION_STATUS_SUCCESSFUL — a missing URL means “not yet”, not “failed”, so read the field before using it and treat its absence as a retry condition. A media item that failed generation never carries a URL, and retrying will not produce one.

const url = media.videoUrl;
if (!url) {
  // Not an error — the link is not available yet. See the options below.
}

Which route to use depends on whether you can wait.

If you are already polling the job, do nothing special. Completed video jobs re-resolve missing URLs automatically on GET /jobs/jobId, and the recovered link is saved, so a later poll returns it with no extra work on your side. This applies to video jobs created within the last 24 hours. Once the job is completed and a URL is still missing, leave at least a minute between polls — a job re-resolves at most once a minute, and the block clears only once traffic stops, so a tight retry loop lengthens the wait rather than shortening it.

If you hold a mediaGenerationId but no longer have the job, ask for that one media again with GET /assets/mediaGenerationId. That endpoint says which case you are in rather than leaving you to guess. A 503 with a Retry-After header means the link is coming and tells you how long to wait, so wait that long and ask again. A 404 means Google has no such media, and no amount of retrying will change it.

If you cannot wait, download the video through us with GET /assets/mediaGenerationId?raw=true. It reads the media over a different Google route that the block does not touch, so it works immediately and keeps working while the other two return nothing. It is video only.

Prefer the two link-based routes when you can. They hand you a link and you download straight from Google. The raw form moves the whole file through useapi.net on every call, which makes it a way out of a stuck download rather than your normal download path.

Characters and voices resolve their URLs as they are read, so simply requesting GET /characters/ref or GET /voices/ref again is enough. Wait a minute before retrying — a response that came back without its URL is held briefly, so an immediate repeat returns the same one.

None of this applies to images. Whenever an image URL is missing, POST /images puts the image itself in the response instead, base64-encoded in encodedImage — so you already have the picture and there is nothing to retry.

Examples

  • curl -X POST \
         -H "Authorization: Bearer YOUR_API_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
           "prompt": "A serene mountain landscape at sunset with camera slowly panning right",
           "model": "veo-3.1-fast",
           "aspectRatio": "landscape",
           "duration": 8,
           "count": 2
         }' \
         "https://api.useapi.net/v1/google-flow/videos" > response.json
    
    # Extract video URLs using jq
    cat response.json | jq -r '.media[0].videoUrl'
    cat response.json | jq -r '.media[1].videoUrl'
    
    # Download videos using curl
    curl "$(cat response.json | jq -r '.media[0].videoUrl')" --output video_1.mp4
    curl "$(cat response.json | jq -r '.media[1].videoUrl')" --output video_2.mp4
    
  • const token = 'YOUR_API_TOKEN';
    const apiUrl = 'https://api.useapi.net/v1/google-flow/videos';
    
    const response = await fetch(apiUrl, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt: 'A serene mountain landscape at sunset with camera slowly panning right',
        model: 'veo-3.1-fast',
        aspectRatio: 'landscape',
        duration: 8,
        count: 2
      })
    });
    
    const result = await response.json();
    console.log('Generated videos:', result.media.length);
    
    // Download videos
    for (const [index, item] of result.media.entries()) {
      console.log(`Video ${index + 1} seed:`, item.video?.generatedVideo?.seed);
      console.log(`mediaGenerationId:`, item.mediaGenerationId);
      console.log(`Video URL:`, item.videoUrl);
    
      // Download video (Node.js)
      const videoResponse = await fetch(item.videoUrl);
      const videoBuffer = await videoResponse.arrayBuffer();
      const fs = require('fs');
      fs.writeFileSync(`generated_video_${index + 1}.mp4`, Buffer.from(videoBuffer));
    }
    
  • import requests
    
    token = 'YOUR_API_TOKEN'
    api_url = 'https://api.useapi.net/v1/google-flow/videos'
    
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    
    data = {
        'prompt': 'A serene mountain landscape at sunset with camera slowly panning right',
        'model': 'veo-3.1-fast',
        'aspectRatio': 'landscape',
        'duration': 8,
        'count': 2
    }
    
    response = requests.post(api_url, headers=headers, json=data)
    result = response.json()
    
    print(f"Generated {len(result['media'])} videos")
    
    # Download videos
    for index, item in enumerate(result['media']):
        video = item.get('video', {}).get('generatedVideo', {})
        print(f"Video {index + 1} seed:", video.get('seed'))
        print(f"mediaGenerationId:", item.get('mediaGenerationId'))
    
        # Download video
        video_response = requests.get(item['videoUrl'])
        with open(f'generated_video_{index + 1}.mp4', 'wb') as f:
            f.write(video_response.content)
    

Try It