Uploading Images

To fully leverage the Scenario API for image and content generation, you often need to provide input assets, such as reference images for img2img, ControlNet, or IP-Adapter, or source images for inpainting. The postAsset endpoint allows you to programmatically upload these images to your project, making them accessible for subsequent generation tasks. This article will guide you through the process of using the postAsset endpoint, detailing its functionality, parameters, and providing practical code examples.

Understanding the `postAsset` Endpoint

The postAsset endpoint is your gateway for bringing external visual data into the Scenario ecosystem. It enables you to upload various types of image files, which are then stored as assets within your project. Once an asset is uploaded, it receives a unique assetId, which can then be referenced in other API calls, such as those for image generation, video creation, or 3D model generation.

This endpoint is crucial for workflows that involve:

Image-to-Image Transformations: Providing a base image to be modified or styled.
ControlNet Guidance: Supplying images for pose, depth, or edge control.
IP-Adapter References: Uploading images to guide style or character consistency.
Inpainting/Outpainting: Supplying the image to be edited and the mask.

Endpoint Details

The postAsset endpoint is a POST request to the /v1/assets path:

POST https://api.cloud.scenario.com/v1/assets - API Reference

Request Body

The primary component of the request body is the image itself. While the API reference for postasset doesn't explicitly list parameters beyond the file, typical asset upload scenarios might involve metadata. However, based on the provided API documentation, the core requirement is the file data.

Parameter	Type	Description
`image`	file	Required. The image to upload in base64 format string

Note: Ensure your request includes the Content-Type: multipart/form-data header when sending the file.

Code Examples

Here are examples of how to upload an asset using the postAsset endpoint in different programming languages.

Python

import requests
import base64
import json

api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"

url = "https://api.cloud.scenario.com/v1/assets"

# Read and encode image as base64
file_path = "./my_image.png"
with open(file_path, "rb") as image_file:
    encoded_string = base64.b64encode(image_file.read()).decode("utf-8")

# JSON payload
payload = {
    "image": encoded_string,
    "name": "my_image_base64_upload",
}

headers = {
    "Content-Type": "application/json"
}

# Make request with basic auth
response = requests.post(url, headers=headers, data=json.dumps(payload), auth=(api_key, api_secret))

# Handle response
if response.status_code == 200:
    data = response.json()
    asset_id = data.get("asset", {}).get("assetId")
    print(f"Asset uploaded successfully! Asset ID: {asset_id}")
    print("Response:", data)
else:
    print(f"Error uploading asset: {response.status_code} - {response.text}")

Node.js

const fetch = require("node-fetch");
const fs = require("fs");
const path = require("path");

const apiKey = "YOUR_API_KEY";
const apiSecret = "YOUR_API_SECRET";
const credentials = Buffer.from(`${apiKey}:${apiSecret}`).toString("base64");

async function uploadAsset() {
  const url = "https://api.cloud.scenario.com/v1/assets";
  const filePath = "./my_image.png"; // Local image path

  try {
    // Read and encode image to Base64
    const fileBuffer = fs.readFileSync(filePath);
    const base64Image = fileBuffer.toString("base64");

    // Prepare JSON payload
    const payload = {
      image: base64Image,
      type: "image", // or "texture", "normal-map", etc.
      name: path.basename(filePath),
      metadata: {
        source: "base64"
      }
    };

    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Authorization": `Basic ${credentials}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload)
    });

    const data = await response.json();

    if (response.ok) {
      const assetId = data.asset.assetId;
      console.log(`Asset uploaded successfully! Asset ID: ${assetId}`);
      console.log("Response:", data);
    } else {
      console.error(`Error uploading asset: ${response.status} - ${JSON.stringify(data)}`);
    }
  } catch (error) {
    console.error("Error:", error.message || error);
  }
}

uploadAsset();

Note: Replace ./my_image.png with the actual path to your file.

Response

A successful response to a postAsset request will return an HTTP 200 OK status code and a JSON object containing details about the newly uploaded asset:

{
    "asset": {
        "id": "asset_staging_qSACAtKeAbd1EmAEG4YNguea",
        "url": "https://cdn.cloud.scenario.com/assets-transform/asset_staging_qSACAtKeAbd1EmAEG4YNguea?p=100&Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9jZG4uc3RhZ2luZy5waG9lbml4LW1haW4uc2NlbmFyaW8tbGFicy5pby9hc3NldHMtdHJhbnNmb3JtL2Fzc2V0X3N0YWdpbmdfcVNBQ0F0S2VBYmQxRW1BRUc0WU5ndWVhP3A9MTAwKiIsIkNvbmRpdGlvbiI6eyJEYXRlTGVzc1RoYW4iOnsiQVdTOkVwb2NoVGltZSI6MTc1MTkzMjc5OX19fV19&Key-Pair-Id=K2GSFL33JG2KAK&Signature=bkB76xH-OSj2xAjTM1YEbf5d%7Ep1B3mCvUYYXvgmqMAmfcajBPAjEGCBLTCU%7Eq7Fp2NMgUt5bKj0KbRs07JOhiu5fLvLwrP9LR-PNmwnsTa2aHpG6VhURNyFxOE4V%7EDHbpCmyh29E3z7vjEvMcFbO8kK7wPa8ne6hV5ZFIYDXZuoh3Z3hnglKniK-G9uvzTbGqYDaxFx109tEzSbqmgiLa-1KspWdcmGp8CP4n30u0SXTnjRlfDlA__",
        "mimeType": "image/png",
        "metadata": {
            "type": "uploaded",
            "name": "fileName.png",
            "kind": "image",
            "width": 1024,
            "height": 1024,
            "size": 979892
        },
        "properties": {
            "width": 1024,
            "height": 1024,
            "size": 979892
        },
        "kind": "image",
        "source": "uploaded",
        "ownerId": "proj_eTyi419soRtdN2AexdFHZDqX",
        "authorId": "03223725c4b2d23114ab7d673bcbf850",
        "createdAt": "2025-06-30T15:15:27.153Z",
        "updatedAt": "2025-06-30T15:15:27.153Z",
        "privacy": "private",
        "tags": [],
        "collectionIds": [],
        "status": "success",
        "editCapabilities": [
            "REMOVE_BACKGROUND",
            "REFINE",
            "PIXELATE",
            "PROMPT_EDITING",
            "UPSCALE",
            "UPSCALE_360",
            "DETECTION",
            "VECTORIZATION",
            "SEGMENTATION",
            "REFRAME",
            "GENERATIVE_FILL"
        ]
    }
}

Key fields in a successful response include:

id: The unique identifier for the uploaded asset. This ID is crucial for referencing the asset in subsequent API calls (e.g., for imageUrl in img2img requests).
url: The URL where the uploaded asset can be accessed. This is typically a permanent link to the file.
filename: The original filename of the uploaded asset.
mimetype: The MIME type of the uploaded file (e.g., image/png, image/jpeg).
size: The size of the uploaded file in bytes.
createdAt: Timestamp of when the asset was uploaded.

By effectively using the postAsset endpoint, you can seamlessly integrate your own visual content into the Scenario API workflows, enabling more personalized and powerful AI-driven creations.