Upload Assets

April 6, 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 Luma CDN for use in video generation (keyframes, character reference) and image generation (style/character references). Supported formats are JPEG, PNG, and WebP with a maximum file size of 20 MB.

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

The returned assetRef is used as imageStart, imageEnd, or imageCharacter in POST /videos, and as imageRef1..4 in POST /images.

Assets are stored for 30 days.

https://api.useapi.net/v1/luma/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 required, the Luma account email address.

Request Body

Binary image content (raw bytes).

Responses

  • 200 OK

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

    {
  "assetRef": "u12345-email:[email protected]:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "[email protected]",
  "upload": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "media": {
      "url": "https://storage.cdn-luma.com/uploads/..."
    }
  }
}
    • assetRef - Reference ID for use in POST /videos as the image parameter.
    • email - Account used for the upload.
    • upload.id - Luma upload identifier.
    • upload.media.url - CDN URL of the uploaded image.

    assetRef format: u{userid}-email:{email}-image:{uuid}

  • 400 Bad Request

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

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

    {
  "error": "Content is empty"
}

  • 401 Unauthorized

    Invalid API token.

    {
  "error": "Unauthorized"
}

  • 404 Not Found

    Account not found or not configured.

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

  • 596 Session Error

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

    {
  "error": "Luma account has an error. Please check your account configuration via GET /v1/luma/accounts or re-add the account via POST /v1/luma/accounts"
}

Model 

{
  assetRef: string                // Reference ID for POST /videos image param
  email: string                   // "[email protected]"
  upload: {
    id: string                    // Luma upload UUID
    media: {
      url: string                 // CDN URL of uploaded image
    }
  }
  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/luma/assets/[email protected]"

  • const token = 'YOUR_API_TOKEN'
const email = '[email protected]'

const apiUrl = `https://api.useapi.net/v1/luma/assets/${encodeURIComponent(email)}`

// 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'
email = '[email protected]'

api_url = f'https://api.useapi.net/v1/luma/assets/{quote(email, 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