Upscale Videos

January 20, 2026 (November 16, 2026)

Table of contents

  1. Request Headers
  2. Request Body
  3. Responses
  4. Model
  5. Missing media URLs
    1. How to get the link
  6. Examples
  7. Try It

Upscale a previously generated video to 720p, 1080p or 4K resolution.

Seeing “Upscaling failed” in Flow? Why Google Flow upscales fail and how to fix it.

  • Video upscaling requires a paid Google AI subscription. Free accounts cannot upscale at any resolution.
  • 4K requires a Google AI Ultra subscription. Other paid accounts can use 720p and 1080p.
  • A resolution your account’s plan does not include answers 400 with 4K upscaling is not available for this account (or 720p / 1080p on a free account). The request is refused before a reCAPTCHA token is solved, so it costs you nothing, and retrying will not change the outcome.
  • 720p and 1080p upscaling are free for a video of up to 10 seconds, then 1 credit for each second above 10 (a 15-second video costs 5). 4K costs 50 credits up to 10 seconds, then 5 more for each second above 10 (75 for 15 seconds).
  • Google upscales videos of up to 15 seconds. A longer video, such as one made longer with POST /videos/extend, answers 400 before any captcha is solved.
  • 720p is for promoting a 360p Omni clip (Omni 1.2 Flash or Omni 1.1 Flash), generated with resolution: 360p. For a video of up to 10 seconds, generating at 360p and upscaling afterwards costs a third of generating at 720p directly on Omni 1.2 Flash, and about half on Omni 1.1 Flash.
  • Video upscaling typically completes within 30-60 seconds, with 4K taking a few minutes.
  • Upscaling the same video twice returns a cached result (no additional credits consumed). Use the video URL from the first upscale response.

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

Request Headers

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

Request Body

{
  "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMx...",
  "resolution": "1080p"
}
  • mediaGenerationId is required. The mediaGenerationId from a previously generated video via POST /videos.
  • resolution is optional. Target resolution for upscaling (default: 1080p).
    Supported values: 720p, 1080p, 4K. Use 720p on a 360p Omni clip. A 360p clip can also go straight to 1080p.
  • 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.
  • 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.
  • captchaToken, captchaRetry, captchaOrder are optional, mutually exclusive captcha parameters. See Captcha Parameters for details.

Responses

  • 200 OK

    Video upscaled successfully. Both operations[] (older shape, with fifeUrl) and media[] (current, with videoUrl) are populated.

    {
      "jobId": "j1115123456789617024v-u12345-email:[email protected]:google-flow",
      "operations": [
        {
          "operation": {
            "name": "2fefd089-...redacted...",
            "metadata": {
              "@type": "type.googleapis.com/google.internal.labs.aisandbox.v1.Media",
              "name": "2fefd089-...redacted...",
              "video": {
                "seed": 0,
                "model": "veo_3_1_upsampler_1080p",
                "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
                "isLooped": false,
                "upsampleResolution": "VIDEO_UPSAMPLE_RESOLUTION_1080P",
                "fifeUrl": "https://flow-content.google/video/2fefd089-...redacted...?Expires=...",
                "servingBaseUri": "https://flow-content.google/image/2fefd089-...redacted...?Expires=...",
                "mediaGenerationId": "user:12345-email:6a6f...-video:2fefd089-...redacted...",
                "mediaVisibility": "PRIVATE"
              }
            }
          },
          "sceneId": "",
          "status": "MEDIA_GENERATION_STATUS_SUCCESSFUL",
          "mediaGenerationId": "user:12345-email:6a6f...-video:2fefd089-...redacted..."
        }
      ],
      "media": [
        {
          "name": "2fefd089-...redacted...",
          "projectId": "9f63078c-...redacted...",
          "workflowId": "66612805-...redacted...",
          "workflowStepId": "CAI",
          "mediaMetadata": {
            "createTime": "2026-11-15T23:31:41.145235Z",
            "mediaBlobSize": "14417920",
            "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_SUCCESSFUL" },
            "visibility": "PRIVATE",
            "requestData": {
              "videoGenerationRequestData": {
                "backend": "flow",
                "statusEnum": 3,
                "aspectEnum": 2,
                "videoModelControlInput": {
                  "videoModelName": "veo_3_1_upsampler_1080p",
                  "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
                  "videoResolution": "VIDEO_RESOLUTION_1080P"
                }
              },
              "clientPlatform": "CLIENT_PLATFORM_WEB"
            }
          },
          "video": {
            "generatedVideo": {
              "seed": 0,
              "prompt": "",
              "model": "veo_3_1_upsampler_1080p",
              "baseImageMediaGenerationId": "",
              "isLooped": false,
              "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
              "upsampleMetadata": { "videoUpsampleResolution": "VIDEO_UPSAMPLE_RESOLUTION_1080P" }
            },
            "operation": { "name": "2fefd089-...redacted..." }
          },
          "videoUrl": "https://flow-content.google/video/2fefd089-...redacted...?Expires=...",
          "thumbnailUrl": "https://flow-content.google/image/2fefd089-...redacted...?Expires=...",
          "mediaGenerationId": "user:12345-email:6a6f...-video:2fefd089-...redacted..."
        }
      ],
      "remainingCredits": 18760,
      "captcha": {
        "service": "CapSolver",
        "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e",
        "durationMs": 3500,
        "attempts": [
          {
            "service": "CapSolver",
            "success": true,
            "durationMs": 3500,
            "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e"
          }
        ]
      }
    }
    
  • 201 Created

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

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

    {
      "jobid": "j1115123456789617024v-u12345-email:[email protected]:google-flow",
      "type": "video",
      "status": "created",
      "created": "2026-11-15T12:34:56.789Z",
      "request": {
        "mediaGenerationId": {
          "user": 12345,
          "email": "[email protected]",
          "type": "video",
          "id": "a1d95d21-75d2-482d-a354-14ef8802ce66",
          "referenceId": "user:12345-email:6a6f...-video:a1d95d21-75d2-482d-a354-14ef8802ce66"
        },
        "resolution": "1080p",
        "async": true,
        "email": "[email protected]"
      },
      "response": {
        "media": [
          {
            "name": "2fefd089-...redacted...",
            "projectId": "9f63078c-...redacted...",
            "workflowId": "66612805-...redacted...",
            "workflowStepId": "CAI",
            "mediaMetadata": {
              "createTime": "2026-11-15T23:31:41.145235Z",
              "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_PENDING" },
              "visibility": "PRIVATE",
              "requestData": {
                "videoGenerationRequestData": {
                  "backend": "flow",
                  "statusEnum": 1,
                  "aspectEnum": 2,
                  "videoModelControlInput": {
                    "videoModelName": "veo_3_1_upsampler_1080p",
                    "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
                    "videoResolution": "VIDEO_RESOLUTION_1080P"
                  }
                },
                "clientPlatform": "CLIENT_PLATFORM_WEB"
              }
            },
            "video": {
              "generatedVideo": {
                "seed": 0,
                "prompt": "",
                "model": "veo_3_1_upsampler_1080p",
                "baseImageMediaGenerationId": "",
                "isLooped": false,
                "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
                "upsampleMetadata": { "videoUpsampleResolution": "VIDEO_UPSAMPLE_RESOLUTION_1080P" }
              },
              "operation": { "name": "2fefd089-...redacted..." }
            }
          }
        ],
        "operations": [
          {
            "operation": { "name": "2fefd089-...redacted..." },
            "sceneId": "",
            "status": "MEDIA_GENERATION_STATUS_PENDING"
          }
        ],
        "captcha": {
          "service": "CapSolver",
          "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e",
          "durationMs": 5357,
          "attempts": [
            {
              "service": "CapSolver",
              "success": true,
              "durationMs": 5357,
              "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e"
            }
          ]
        },
        "captchaAttemptsCount": 1,
        "captchaProviders": "CapSolver",
        "tier": "PAYGATE_TIER_TWO",
        "sku": "G1_TIER2",
        "remainingCredits": 18760
      }
    }
    
  • 400 Bad Request

    Invalid request, or a resolution your account’s plan does not include (4K needs Google AI Ultra).

    {
      "error": "4K upscaling is not available for this account",
      "code": 400
    }
    
  • 401 Unauthorized

    Invalid API token.

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

    Your useapi.net subscription is missing or has expired, so nothing was sent to Google. Subscribe or renew it, then send the request again.

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

    When the subscription has expired:

    {
      "error": "useapi.net ⁝ Monthly subscription 261008 expired, please renew your subscription before submitting new 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 [email protected], 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 video not found.

    {
      "error": "Google Flow account [email protected] not found",
      "code": 404
    }
    
  • 408 Request Timeout

    Video upscaling polling timeout (after 10 minutes).

    {
      "error": "Polling timeout",
      "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 [email protected] 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 upscaled video (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 upscaling completed. Returns the upscaled video with signed URLs, in media[] and, for older clients, in operations[]. FlowVideoMedia and FlowCaptcha are described below the tabs.

    {
      jobId: string                              // the job id, for GET /jobs/{jobid}
      operations: Array<{                        // older shape, kept for clients that read fifeUrl: one per media[] item
        operation: {                             // the upscale operation
          name: string                           // the same as media[].name
          metadata?: {                           // the upscaled video, copied from media[] (left out when Google reports no video details)
            '@type': string                      // always the same type name, Google's media record
            name: string                         // the same as media[].name
            video: {                             // the upscaled video
              seed: number                       // the seed Google reports (0 on an upscale)
              model: string                      // Google's own key for the upscale model
              aspectRatio: string                // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT
              isLooped: false                    // always false
              prompt?: string                    // left out on an upscale (it has no prompt)
              upsampleResolution?: string        // VIDEO_UPSAMPLE_RESOLUTION_720P | VIDEO_UPSAMPLE_RESOLUTION_1080P
                                                 // (left out for 4K)
              fifeUrl?: string                   // signed MP4 download URL, as media[].videoUrl
              servingBaseUri?: string            // signed thumbnail URL, as media[].thumbnailUrl (the video URL when there is none)
              mediaGenerationId: string          // the upscaled video's id, as media[].mediaGenerationId
              mediaVisibility?: string           // "PRIVATE", as media[].mediaMetadata.visibility
            }
          }
        }
        sceneId: ''                              // always an empty string
        status: string                           // MEDIA_GENERATION_STATUS_SUCCESSFUL | MEDIA_GENERATION_STATUS_FAILED, as media[]
        mediaGenerationId: string                // the upscaled video's id, as media[].mediaGenerationId
      }>
      media: FlowVideoMedia[]                    // the upscaled 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. The video you sent comes back decoded, as a FlowReference object (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
        mediaGenerationId: FlowReference         // the video to upscale
        resolution?: string                      // 720p, 1080p or 4K
        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
        email: string                            // the account the job runs on, the one that owns the video
      }
      response: {                                // Google's answer so far
        media: FlowVideoMedia[]                  // the upscale, still being made (no mediaGenerationId or URLs yet)
        operations: Array<{                      // older shape: one per media[] item
          operation: {                           // the upscale operation
            name: string                         // the same as media[].name
          }
          sceneId: ''                            // always an empty string
          status: string                         // MEDIA_GENERATION_STATUS_PENDING at this point
        }>
        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 Google's own error object when Google
                                                 // could not read the source video (answered before a job exists, so with no jobId or code)
        code: number                             // HTTP status Google answered, e.g. 404
        message: string                          // the error message
        status: string                           // Google's status name
        details: Array<{                         // Google's error details
          '@type': string                        // the type name of the detail
          reason: string                         // Google's reason code
        }>
      }
      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.
                                                 // Present only when all videos failed AND Google gave a reason. See
                                                 // "Why a generation failed" on the POST /videos page
        operations?: object[]                    // the older operations[] shape of the 200 answer, one per media[] item
        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 p0UkFb 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
      }
    }
    

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: the video to upscale, mediaGenerationId 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

  • # First generate a video
    curl -X POST \
         -H "Authorization: Bearer YOUR_API_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{"prompt": "A serene mountain landscape at sunset"}' \
         "https://api.useapi.net/v1/google-flow/videos" > generate.json
    
    # Extract mediaGenerationId from the response
    MEDIA_ID=$(jq -r '.media[0].mediaGenerationId' generate.json)
    
    # Upscale the video to 1080p
    curl -X POST \
         -H "Authorization: Bearer YOUR_API_TOKEN" \
         -H "Content-Type: application/json" \
         -d "{\"mediaGenerationId\": \"$MEDIA_ID\", \"resolution\": \"1080p\"}" \
         "https://api.useapi.net/v1/google-flow/videos/upscale" > upscale.json
    
    # Extract upscaled video URL and download
    VIDEO_URL=$(jq -r '.media[0].videoUrl' upscale.json)
    curl "$VIDEO_URL" --output upscaled_video.mp4
    
  • const token = 'YOUR_API_TOKEN';
    
    // First generate a video
    const generateResponse = await fetch('https://api.useapi.net/v1/google-flow/videos', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt: 'A serene mountain landscape at sunset'
      })
    });
    
    const generated = await generateResponse.json();
    // Prefer media[] over deprecated operations[]
    const mediaGenerationId = generated.media[0].mediaGenerationId;
    
    // Upscale the video
    const upscaleResponse = await fetch('https://api.useapi.net/v1/google-flow/videos/upscale', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        mediaGenerationId,
        resolution: '1080p'
      })
    });
    
    const upscaled = await upscaleResponse.json();
    // Prefer media[] over deprecated operations[]
    const videoUrl = upscaled.media[0].videoUrl;
    
    // Download upscaled video (Node.js)
    const videoResponse = await fetch(videoUrl);
    const videoBuffer = await videoResponse.arrayBuffer();
    require('fs').writeFileSync('upscaled_video.mp4', Buffer.from(videoBuffer));
    console.log('Upscaled video saved!');
    
  • import requests
    
    token = 'YOUR_API_TOKEN'
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    
    # First generate a video
    generate_response = requests.post(
        'https://api.useapi.net/v1/google-flow/videos',
        headers=headers,
        json={'prompt': 'A serene mountain landscape at sunset'}
    )
    generated = generate_response.json()
    # Prefer media[] over deprecated operations[]
    media_generation_id = generated['media'][0]['mediaGenerationId']
    
    # Upscale the video
    upscale_response = requests.post(
        'https://api.useapi.net/v1/google-flow/videos/upscale',
        headers=headers,
        json={
            'mediaGenerationId': media_generation_id,
            'resolution': '1080p'
        }
    )
    upscaled = upscale_response.json()
    # Prefer media[] over deprecated operations[]
    video_url = upscaled['media'][0]['videoUrl']
    
    # Download upscaled video
    video_response = requests.get(video_url)
    with open('upscaled_video.mp4', 'wb') as f:
        f.write(video_response.content)
    print('Upscaled video saved!')
    

Try It