Upload an asset

October 7, 2026 (November 16, 2026)

Table of contents

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

Upload an image or a video to one of your accounts and get an assetId for it. The file is sent as the raw request body with its MIME type in the Content-Type header (no multipart, no JSON).

Where an assetId goes:

  • An image is a startImage or a referenceImage_1..referenceImage_3 of POST /videos. An image made with POST /images needs no upload: pass its mediaId there directly.
  • Uploaded videos cannot be edited: Google refuses every edit of an uploaded video. To edit a clip, pass the mediaId of a clip made with this API to POST /videos/edit.
  • An image is also a person’s photo to start an avatar from (image), or a logo to place on an avatar’s clothes (logo), in POST /avatars.

The assetId names the account the file was uploaded to, and only jobs on that account can use it. To use several uploads in one video or avatar, upload them all to the same account with email. An upload takes no maxJobs slot, uses no allowance, and works even on an account whose allowance is used up for the month.

Uploads are temporary like every Vids file, so upload an input shortly before the job that uses it. See How long files last.

https://api.useapi.net/v1/google-vids/assets?email=email

Request Headers
Authorization: Bearer {API token}
Content-Type: image/jpeg   # image/jpeg, image/png, image/webp or video/mp4
  • API token is required, see Setup useapi.net for details.
  • Content-Type is required, the file’s MIME type.
    Supported values: image/jpeg, image/png, image/webp, video/mp4.

The request body is the file’s raw bytes, from 1 byte to 50 MB.

Query Parameters
  • email is optional, the account to upload to, used as given whatever its plan (a free account included, for an avatar photo or logo). When omitted, a healthy account with a video allowance is picked at random, preferring one whose video seconds are not used up this month. URL-encode it.
Responses
  • 200 OK

    {
      "assetId": "user:[email protected]:AYGXpjjhK1XnT8IYzCoB9dCO4XxlyHvHv54IZep9pWDRq7fNu8bo7WF-qhIC6OzxYEVNrPLOm1e5x9BrxROKgHRUCIeFWQ_r1tRbzBHTMGfER_jmittzbVWQfvZjzrU2Qv4CyCZtaeJMoqfkPWgZMA5QmCoS8zRLIeapAuj5lYbhjWQgIfRrmdA",
      "email": "[email protected]",
      "type": "image/jpeg",
      "bytes": 113184
    }
    
  • 400 Bad Request — an unsupported Content-Type, an empty body, or a file over 50 MB.

    {
      "error": "Content-Type must be one of image/jpeg, image/png, image/webp, video/mp4 (raw file bytes in the body)",
      "code": 400
    }
    
    {
      "error": "File must be 1 byte to 50 MB",
      "code": 400
    }
    
  • 401 Unauthorized

    Invalid API token.

    {
      "error": "useapi.net ⁝ Unauthorized",
      "code": 401
    }
    
  • 404 Not Found — the account named by email is not connected.

    {
      "error": "Account [email protected] is not configured",
      "code": 404
    }
    
  • 503 Service Unavailable — Google did not accept the upload. Retry shortly.

    {
      "error": "Google error: Upload failed (HTTP 500)",
      "code": 503
    }
    
  • 596 Account Error

    Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via Setup Google Vids.

    {
      "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.",
      "code": 596
    }
    
    {
      "error": "Account [email protected]: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids",
      "code": 596
    }
    
Model

The new assetId, the account the file was uploaded to, its Content-Type and its size in bytes.

The uploaded file, field by field
{ // TypeScript, all fields are optional
  assetId: string     // user:<id>-<email>-asset:<Google upload id>, pass it as startImage, referenceImage_N or video, or as image or logo of POST /avatars
  email: string       // the account the file was uploaded to
  type: string        // the Content-Type you sent
  bytes: number       // the file size
  error?: string      // errors only
  code?: number       // errors only
}
Examples
  • curl -X POST "https://api.useapi.net/v1/google-vids/assets?email=user%40example.com" \
       -H "Authorization: Bearer …" \
       -H "Content-Type: image/jpeg" \
       --data-binary @dog.jpg
    
  • import fs from "fs";
    const token = "API token";
    const email = "Previously configured account email";
    const apiUrl = `https://api.useapi.net/v1/google-vids/assets?email=${encodeURIComponent(email)}`;
    const response = await fetch(apiUrl, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "image/jpeg",
      },
      body: fs.readFileSync("dog.jpg")
    });
    const result = await response.json();
    console.log("response", {response, result});
    
  • import requests
    token = "API token"
    email = "Previously configured account email"
    apiUrl = "https://api.useapi.net/v1/google-vids/assets"
    headers = {
        "Authorization" : f"Bearer {token}",
        "Content-Type": "image/jpeg"
    }
    with open("dog.jpg", "rb") as f:
        response = requests.post(apiUrl, headers=headers, params={"email": email}, data=f.read())
    print(response, response.json())
    
Try It