Upload Assets

February 23, 2026 (March 2, 2026)

Table of contents

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

Upload images to Dreamina for use as video or image generation reference frames. Supported formats are JPEG, PNG, and WebP with a maximum file size of 10 MB.

Content-Type File Extension
image/jpeg jpeg, jpg
image/png png
image/webp webp

The returned assetRef is used as firstFrameRef, endFrameRef, or frame_N_imageRef in POST /videos, and as imageRef_N in POST /images.

https://api.useapi.net/v1/dreamina/assets/account

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

  • account is required.

Request Body

Binary image content (raw bytes).

Responses

  • 200 OK

    Image uploaded successfully. Returns the assetRef for use in video and image generation.

    {
  "assetRef": "US:[email protected]:w685:h900:s86866-uri:tos-useast5-i-wopfjsm1ax-tx/3605b150c6b949f5acea2eac3ca59544",
  "account": "US:[email protected]",
  "width": 685,
  "height": 900,
  "size": 86866
}
    • assetRef - Reference ID for use in POST /videos as firstFrameRef, endFrameRef, or frame_N_imageRef, and in POST /images as imageRef_N.
    • width - Image width in pixels.
    • height - Image height in pixels.
    • size - Image size in bytes.
    • account - Account used for the upload.

    assetRef format: <account>-image:w<width>:h<height>:s<size>-uri:<nativeUri>

  • 400 Bad Request

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

    {
  "error": "Content-Type (image/bmp) not supported. Valid values: image/jpeg, image/png, image/webp"
}

    {
  "error": "Image is empty"
}

  • 401 Unauthorized

    Invalid API token.

    {
  "error": "Unauthorized"
}

  • 404 Not Found

    Account not found or not configured.

    {
  "error": "Unable to find configuration for account US:[email protected]"
}

  • 596 Session Error

    Account session expired. Re-add the account using POST /accounts with correct credentials.

    {
  "error": "Session expired"
}

Model 

{
  assetRef: string                // Reference ID for POST /videos and POST /images
  account: string                 // "US:[email protected]"
  width: number                   // Image width in pixels
  height: number                  // Image height in pixels
  size: number                    // Image size in bytes
  imageRef?: string               // Legacy alias for assetRef (backward compatibility)
  error?: string                  // Error message
}

Examples 

  • 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/dreamina/assets/US:[email protected]"

  • const token = 'YOUR_API_TOKEN';
const account = 'US:[email protected]';

const apiUrl = `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(account)}`;

// Load image - Example 1: From local file (Node.js)
const fsp = require('fs').promises;
const blob = new Blob([await fsp.readFile('./image.jpeg')]);

// Load image - Example 2: From file input element
// 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('assetRef:', result.assetRef);

  • import requests
from urllib.parse import quote

token = 'YOUR_API_TOKEN'
account = 'US:[email protected]'

api_url = f'https://api.useapi.net/v1/dreamina/assets/{quote(account, safe="")}'

with open('./image.jpeg', '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('assetRef:', result.get('assetRef'))

Try It