Upload Assets

November 17, 2025 (November 16, 2026)

Table of contents

  1. Request Headers
  2. Path Parameters
  3. Request Body
  4. Responses
  5. Model
    1. Image upload response
    2. Video upload response
  6. Examples
  7. Try It

Upload assets to Google Flow. Supports image and video uploads:

Content-Type File Extension Max size
image/png png 20 MB
image/jpeg jpeg 20 MB
image/webp webp 20 MB
video/mp4 mp4 100 MB

POST raw content using Make.com and similar nocode tools.

Uploads stay on the Google account after the generation that used them finishes, and nothing removes them on its own. Over a long-running integration they add up. To see what an account is holding, use GET /assets/media/email — it marks uploads with likelyUpload — and clear them with DELETE /assets/email.

https://api.useapi.net/v1/google-flow/assets/email

Request Headers

Authorization: Bearer {API token}
Content-Type: select from the table above
  • API token is required, see Setup useapi.net for details.
  • Content-Type is required, see table above.

Path Parameters

  • email is optional. The email address of the Google Flow account to use (URL-encoded if necessary).

    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 image generation job statistics to select the healthiest account.

    Note: The endpoint can be called as either POST /assets (no email) or POST /assets/:email (explicit email).

Request Body

Binary file contents (raw bytes). Set Content-Type to match the file:

  • image/png, image/jpeg, image/webp for image uploads
  • video/mp4 for video uploads (used as referenceVideo_1 in an Omni V2V edit with omni-flash-1.2 or omni-flash, or as the source of POST /videos/extend)

The image and video paths return slightly different response shapes — see the 200 response below.

Responses

  • 200 OK

    Upload successful. The response shape differs between image and video uploads — see both below.

    Image upload response

    Returned when Content-Type is image/png, image/jpeg, or image/webp.

    {
      "media": {
        "name": "ff9aa5cc-...redacted...",
        "projectId": "5c37e988-...redacted...",
        "workflowId": "69603881-...redacted...",
        "workflowStepId": "",
        "mediaMetadata": {
          "createTime": "2026-02-27T16:34:25.128454Z",
          "requestData": {
            "clientPlatform": "CLIENT_PLATFORM_WEB"
          },
          "visibility": "PRIVATE"
        },
        "image": {
          "userUploadedImage": {
            "aspectRatio": "IMAGE_ASPECT_RATIO_UNSPECIFIED"
          },
          "dimensions": {
            "width": 1024,
            "height": 1024
          }
        }
      },
      "workflow": {
        "name": "69603881-...redacted...",
        "metadata": {
          "displayName": "upload.webp",
          "createTime": "2026-02-27T16:34:25.128454Z",
          "primaryMediaId": "ff9aa5cc-...redacted..."
        },
        "projectId": "5c37e988-...redacted..."
      },
      "mediaGenerationId": {
        "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-...redacted..."
      },
      "width": 1024,
      "height": 1024,
      "email": "john@gmail.com"
    }
    
    Field Description
    media Full media object from Google Flow API with upload details and dimensions
    media.image.dimensions Image dimensions as reported by Google (width and height)
    workflow Workflow metadata including display name and project ID
    mediaGenerationId.mediaGenerationId Reference ID for use in subsequent API calls. Format: user:{userid}-email:{hex_encoded_email}-image:{internal_media_id}. Pass this to GET /assets/mediaGenerationId to read back the original bytes via a signed URL.
    width Image width in pixels
    height Image height in pixels
    email Account email that was used for the upload (useful when email was omitted and auto-selected via load balancing)

    Video upload response

    Returned when Content-Type is video/mp4. Use the returned mediaGenerationId as referenceVideo_1 on POST /videos with model: "omni-flash-1.2" or model: "omni-flash" to drive V2V edit, or as the mediaGenerationId of POST /videos/extend.

    {
      "media": {
        "name": "07c542b0-...redacted...",
        "projectId": "5c37e988-...redacted...",
        "workflowId": "290a1f7a-...redacted...",
        "mediaMetadata": {
          "createTime": "2026-05-20T23:04:23.089821Z",
          "requestData": { "clientPlatform": "CLIENT_PLATFORM_WEB" },
          "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_PENDING" },
          "visibility": "PRIVATE"
        },
        "video": {
          "dimensions": { "width": 1280, "height": 720, "length": "11.940s" },
          "videoOffset": { "startOffset": "0s", "endOffset": "11.940s" },
          "userUploadedVideo": { "encodedVideo": "" }
        }
      },
      "mediaGenerationId": {
        "mediaGenerationId": "user:12345-email:6a6f...-video:07c542b0-...redacted..."
      },
      "durationSeconds": 11.94,
      "width": 1280,
      "height": 720,
      "email": "john@gmail.com"
    }
    
    Field Description
    media Full media object from Google Flow API with upload details and dimensions (mirrors the image response shape, with a video{} sub-object instead of image{})
    media.video.dimensions Video dimensions as reported by Google (width, height, length)
    mediaGenerationId.mediaGenerationId Reference ID for use as referenceVideo_1 on POST /videos. Format: user:{userid}-email:{hex_encoded_email}-video:{internal_media_id}. Also accepted by GET /assets/mediaGenerationId to read back the original bytes via a signed URL.
    durationSeconds Video duration in seconds. Use this to pre-compute endFrameIndex_1 for V2V edit: min(round(durationSeconds × 24), 240)
    width Video width in pixels
    height Video height in pixels
    email Account email that was used for the upload
  • 400 Bad Request

    Invalid request (empty content, unsupported content type, file too large, or content policy violation).

    General error:

    {
      "error": "File size (25165824) is over 20971520 bytes",
      "code": 400
    }
    

    Content policy error:

    {
      "error": {
        "code": 400,
        "message": "Request contains an invalid argument.",
        "status": "INVALID_ARGUMENT",
        "details": [
          {
            "@type": "type.googleapis.com/google.rpc.ErrorInfo",
            "reason": "PUBLIC_ERROR_TRUMP_FACE_DETECTED"
          }
        ]
      }
    }
    

    Image refused earlier: when Google refuses the same image (the exact same file) 10 times with no reason, on at least 2 of your accounts, the API stops sending it to Google for 24 hours after the last refusal and answers right away. Google gives no reason for these refusals: either it does not accept the content, or it cannot read the file. Skip the image, or change it and upload the new version. A refusal that names a reason, like the one above, is never counted.

    {
      "error": {
        "code": 400,
        "message": "Google refused this exact image 10 times on 3 accounts since 2026-10-18T23:18:30.986Z, so it is not sent to Google again before 2026-10-19T23:18:49.314Z. Google gives no reason: either it does not accept the content, or it cannot read the file. Skip this image, or change it (re-export it, crop or edit it) and upload the new version.",
        "status": "INVALID_ARGUMENT",
        "details": []
      }
    }
    
  • 401 Unauthorized

    Invalid API token.

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

    Google refused the upload because it treats the Google account as belonging to someone under 18 (PUBLIC_ERROR_USER_MINOR). Google Flow is not available to such accounts, so retrying will not help. Use another Google account, or have this one’s age verified with Google first. Image uploads need no captcha, so this answer costs no captcha. With email omitted, the load balancer sets the account aside for 1 hour for uploads and generation, then tries it again.

    {
      "error": "Google refused this request because it treats the Google account john@gmail.com as belonging to someone under 18 (PUBLIC_ERROR_USER_MINOR). Google Flow is not available to such accounts, so retrying will not help. Use another Google account, or have this account's age verified with Google first.",
      "code": 403
    }
    
  • 404 Not Found

    Account not found or not configured.

    {
      "error": "Google Flow account john@gmail.com not found",
      "code": 404
    }
    
  • 429 Too Many Requests

    A 429 means Google is rate-limiting the account that handled your upload. Most image-upload 429s carry no reason code. The body is {"error":{"code":429,"message":"flow.google.com maseQ failed","status":"RESOURCE_EXHAUSTED","details":[]}}, with details empty and nothing to read a reason from — the message inside that error object names the upload call that failed, and is not the top-level message described below. That form is handled as USER_REQUESTS_THROTTLED all the same, so everything below applies to it unchanged: the same cooldown, the same Retry-After, the same upload-only quarantine, and the same top-level message and retryAfter fields added alongside Google’s error object.

    Some accounts instead carry one of two reasons:

    Reason Meaning Cooldown
    PUBLIC_ERROR_
    USER_QUOTA_REACHED
    The account’s overall Flow quota cap ~30 min
    PUBLIC_ERROR_
    USER_REQUESTS_THROTTLED
    Google is throttling uploads for this account ~30 min minimum, can persist

    Google meters uploads separately from generation, so USER_REQUESTS_THROTTLED on this endpoint does not mean the account is out of action. The same account can keep serving POST /images and POST /videos normally while every upload is refused.

    They also survive separately. An account that has stopped accepting uploads keeps every image already uploaded to it, and those mediaGenerationId values stay usable as reference_N on that account indefinitely. An account in that state is still worth generating on — it simply cannot take new source material. The limit does clear. Accounts that reached it have uploaded again within about two weeks, and we can’t yet tell whether it resets on a timer or when the account’s monthly subscription renews. Such an account is worth resting rather than replacing. Counting post-assets per account in GET /v2/account/stats shows how much of its upload allowance has been spent.

    The response carries a Retry-After header. Treat it as a minimum wait rather than an estimate of when the limit clears — it is a fixed cooldown, not a per-account prediction, and an upload throttle can sit on an account for hours or days. On USER_REQUESTS_THROTTLED the body also carries a message field spelling this out, and normally a retryAfter timestamp mirroring the header.

    If you passed email, that account is the one being limited — upload to a different account rather than retrying the same one. If you omitted email and have more than one account, the load balancer automatically routes around limited accounts, so you only see a 429 (error: "no_eligible_account") once every account is limited — see GET /jobs › Load Balancing Algorithm. An upload throttle only removes the account from upload routing, so generation requests still reach it.

    A video upload is the exception to everything above. It fails earlier, in Google’s upload-init step, and returns a plain {"error": "Video upload init failed: HTTP 429"} with no reason code, no Retry-After and no message, and it does not quarantine the account.

    On that no_eligible_account response, each skipReasons[].model reports what the account was quarantined for. Uploads carry no model, so entries armed by this endpoint report upload — a routing scope, not a model you can request. On this endpoint the only other value is * (account-wide). On the generation endpoints it is a real model name or *.

  • 503 Service Unavailable

    Google’s upload service is temporarily unavailable. The error is forwarded with a Retry-After header — wait a few seconds and retry. This endpoint uses no captcha provider, so the Captcha service failed 503 does not apply here.

    {
      "error": {
        "code": 503,
        "message": "Service temporarily unavailable.",
        "status": "UNAVAILABLE"
      }
    }
    
  • 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

The uploaded image or video, with Google’s record of it and the mediaGenerationId to use as a reference.

The uploaded image or video, field by field

Image upload response

{
  media: {                              // Full media object from Google Flow API
    name: string                        // Media UUID
    projectId: string                   // the Google Flow project the upload is in
    workflowId: string                  // the Google Flow workflow of the upload
    workflowStepId: string              // Google's workflow step id (empty when Google gives none)
    mediaMetadata: {                    // Google's record of the upload
      createTime?: string               // ISO 8601 timestamp
      requestData?: {                   // how the upload was made, when Google names the platform
        clientPlatform: string          // e.g. "CLIENT_PLATFORM_WEB"
      }
      visibility?: string               // "PRIVATE"
    }
    image: {                            // the uploaded image
      userUploadedImage: {              // marks the media as an upload
        aspectRatio: string             // Google's aspect name, e.g. IMAGE_ASPECT_RATIO_LANDSCAPE or IMAGE_ASPECT_RATIO_PORTRAIT. IMAGE_ASPECT_RATIO_UNSPECIFIED when Google gives none
      }
      dimensions?: {                    // the image size Google read from the file
        width: number                   // pixels
        height: number                  // pixels
      }
    }
  }
  workflow?: {                          // Workflow metadata
    name: string                        // Workflow UUID
    metadata?: {                        // the workflow's details
      displayName?: string              // Original filename
      createTime?: string               // ISO 8601
      primaryMediaId?: string           // Same as media.name
    }
    projectId?: string                  // the Google Flow project of the workflow
  }
  mediaGenerationId: {                  // the reference id, wrapped in an object
    mediaGenerationId: string           // Reference ID: user:{userid}-email:{hex_encoded_email}-image:{internal_media_id}
  }
  width?: number                        // Image width in pixels (absent when neither Google nor the file gives it)
  height?: number                       // Image height in pixels
  email: string                         // Account email used for upload
}

Video upload response

Returned when Content-Type: video/mp4.

{
  media: {                              // Google's record of the upload, as Google returned it (video{} instead of image{})
    name: string                        // Media UUID
    projectId: string                   // the Google Flow project the upload is in
    workflowId: string                  // the Google Flow workflow of the upload
    workflowStepId?: string             // Google's workflow step id, when Google gives one
    mediaMetadata: {                    // Google's record of the upload
      createTime: string                // ISO 8601 timestamp
      requestData: {                    // how the upload was made
        clientPlatform: string          // e.g. "CLIENT_PLATFORM_WEB"
      }
      mediaStatus: {                    // Google's processing status
        mediaGenerationStatus: string   // e.g. "MEDIA_GENERATION_STATUS_PENDING" right after the upload
      }
      visibility: string                // "PRIVATE"
    }
    video: {                            // the uploaded video
      dimensions: {                     // size and duration, as Google reports them
        width: number                   // pixels, as Google reports them (may differ from the file's)
        height: number                  // pixels, as Google reports them
        length: string                  // duration, e.g. "11.940s"
      }
      videoOffset?: {                   // the clip window, set to the whole clip. Present when the duration is known
        startOffset: string             // "0s"
        endOffset: string               // the clip's duration, e.g. "11.940s"
      }
      userUploadedVideo: {              // marks the media as an upload
        encodedVideo: string            // always empty: Google returns no bytes here
      }
    }
  }
  mediaGenerationId: {                  // the reference id, wrapped in an object
    mediaGenerationId: string           // Reference ID: user:{userid}-email:{hex_encoded_email}-video:{internal_media_id}
                                        //   — use as referenceVideo_1 on POST /videos with model omni-flash-1.2 or omni-flash, or as the source of POST /videos/extend
  }
  durationSeconds?: number              // Video duration in seconds
  width?: number                        // Video width in pixels (from upload finalize response)
  height?: number                       // Video height in pixels
  email: string                         // Account email used for upload
}

Examples

  • # Option 1: Without email (auto-selection/load balancing)
    curl -X POST \
         -H "Authorization: Bearer YOUR_API_TOKEN" \
         -H "Content-Type: image/jpeg" \
         --data-binary @/path/to/your/image.jpeg \
         "https://api.useapi.net/v1/google-flow/assets"
    
    # Option 2: With specific email
    curl -X POST \
         -H "Authorization: Bearer YOUR_API_TOKEN" \
         -H "Content-Type: image/jpeg" \
         --data-binary @/path/to/your/image.jpeg \
         "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com"
    
  • const token = 'YOUR_API_TOKEN';
    
    // Option 1: Without email (auto-selection/load balancing)
    const apiUrl = 'https://api.useapi.net/v1/google-flow/assets';
    
    // Option 2: With specific email
    // const email = 'john@gmail.com';
    // const apiUrl = `https://api.useapi.net/v1/google-flow/assets/${encodeURIComponent(email)}`;
    
    // Load image - Example 1: Fetch from URL
    const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg";
    const responseImage = await fetch(imageUrl);
    const blob = await responseImage.blob();
    
    // Load image - Example 2: From local file (Node.js)
    // const fsp = require('fs').promises;
    // const imageFileName = "./cat.png";
    // const blob = new Blob([await fsp.readFile(imageFileName)]);
    
    // Load image - Example 3: From file input element
    // // <input id="image-file" type="file">
    // const imageFile = document.getElementById('image-file');
    // const blob = imageFile.files[0];
    
    const response = await fetch(apiUrl, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': blob.type || 'image/jpeg'
      },
      body: blob
    });
    
    const result = await response.json();
    console.log('Upload result:', result);
    console.log('Reference ID:', result.mediaGenerationId.mediaGenerationId);
    console.log('Account used:', result.email);
    
  • import requests
    from urllib.parse import quote
    
    token = 'YOUR_API_TOKEN'
    
    # Option 1: Without email (auto-selection/load balancing)
    api_url = 'https://api.useapi.net/v1/google-flow/assets'
    
    # Option 2: With specific email
    # email = 'john@gmail.com'
    # api_url = f'https://api.useapi.net/v1/google-flow/assets/{quote(email)}'
    
    # Load image - Example 1: Fetch from URL
    # image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"
    # response_image = requests.get(image_url)
    # file_content = response_image.content
    
    # Load image - Example 2: From local file
    # image_file_path = "./image.jpg"
    # with open(image_file_path, 'rb') as image_file:
    #     file_content = image_file.read()
    
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'image/jpeg'
    }
    
    response = requests.post(
        api_url,
        headers=headers,
        data=file_content
    )
    
    result = response.json()
    print('Upload result:', result)
    print('Reference ID:', result.get('mediaGenerationId', {}).get('mediaGenerationId'))
    print('Account used:', result.get('email'))
    

Try It