Skip to content
Developers
API docs / Features

MAKEUGC PLATFORM API · DOCS V2

Image Ads

Turn product references, brand details and promotional copy into ad images.

Workflow

  1. Prepare one to four product references.
  2. Add brand, promotion and composition details.
  3. Submit and poll for image_urls.
Uses the app's Nano Banana 2 image-ad editing pipeline. The generation service calculates the charge from resolution and image count.
Send X-Api-Key on every MakeUGC request. POST operations require an active paid subscription and a positive credit balance; custom voice creation also requires a plan with custom voices.
Requests are strict JSON: unknown fields, user_id and webhook_url are rejected. Use polling for jobs; these endpoints do not send webhooks.
The outer status boolean indicates request success. Most jobs use data.status: processing, completed or failed; Upscale documents its own statuses. Poll every 5–10 seconds and require a non-empty result URL (or voice_id) before using output.
API credit units × 100 = website display credits. A timeout, network error or 5xx may occur after acceptance: do not automatically resubmit a paid operation. If submission_unknown is true, check the project or contact support with x-request-id; reserved credits remain held until the result is resolved.

Example IDs and media URLs are placeholders. Replace them with values from your account and accessible media files.

Generate image ads #

POST /image-ads/generate

Create branded ads from one to four product references, optional promotion details and a visual prompt.

Request body

Parameter Description
project_id
string
Optional 		Existing project owned by your account. Omit to create one.

Allowed: At least 1 characters; Up to 256 characters

image_urls
string[]
Required 		image urls input.

Allowed: At least 1 items; Up to 4 items

prompt
string
Optional 		prompt input.

Allowed: Up to 2000 characters

brand_name
string
Optional 		brand name input.

Allowed: Up to 200 characters

brand_description
string
Optional 		brand description input.

Allowed: Up to 4000 characters

promotion
object
Optional 		promotion input.
promotion.original_price
string
Optional 		original price input.

Allowed: Up to 100 characters

promotion.promo_price
string
Optional 		promo price input.

Allowed: Up to 100 characters

promotion.details
string
Optional 		details input.

Allowed: Up to 2000 characters

num_images
integer
Optional 		num images input.

Allowed: Minimum 1; Maximum 4

Default: 1

aspect_ratio
string
Optional 		aspect ratio input.

Allowed: 21:9 | 16:9 | 3:2 | 4:3 | 5:4 | 1:1 | 4:5 | 3:4 | 2:3 | 9:16

Default: 1:1

output_format
string
Optional 		output format input.

Allowed: png | jpeg | webp

Default: png

resolution
string
Optional 		resolution input.

Allowed: 1K | 2K | 4K

Default: 1K

Request example

cURL 
curl --fail-with-body --max-time 120 -X POST "https://app.makeugc.ai/api/platform/image-ads/generate" \
  -H "X-Api-Key: $MAKEUGC_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "project_id": "project_123",
  "image_urls": [
    "https://your-cdn.example/product.jpg"
  ],
  "brand_name": "Morning Cup",
  "brand_description": "Reusable ceramic travel cups",
  "prompt": "Minimal product ad with a warm cream background.",
  "promotion": {
    "original_price": "$40",
    "promo_price": "$32",
    "details": "Launch offer"
  },
  "num_images": 1,
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "output_format": "png"
}'
JavaScript 
// Run on your server with Node.js 20+.
const apiKey = process.env.MAKEUGC_API_KEY;
if (!apiKey) throw new Error("Set MAKEUGC_API_KEY first");

const response = await fetch("https://app.makeugc.ai/api/platform/image-ads/generate", {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "project_id": "project_123",
  "image_urls": [
    "https://your-cdn.example/product.jpg"
  ],
  "brand_name": "Morning Cup",
  "brand_description": "Reusable ceramic travel cups",
  "prompt": "Minimal product ad with a warm cream background.",
  "promotion": {
    "original_price": "$40",
    "promo_price": "$32",
    "details": "Launch offer"
  },
  "num_images": 1,
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "output_format": "png"
}),
  signal: AbortSignal.timeout(120000),
});
const text = await response.text();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${text} (request ${response.headers.get("x-request-id")})`);
}
const result = JSON.parse(text);
console.log(result);
Python 
# Install the requests package before running.
import os
import requests

payload = {
    "project_id": "project_123",
    "image_urls": ["https://your-cdn.example/product.jpg"],
    "brand_name": "Morning Cup",
    "brand_description": "Reusable ceramic travel cups",
    "prompt": "Minimal product ad with a warm cream background.",
    "promotion": {
        "original_price": "$40",
        "promo_price": "$32",
        "details": "Launch offer"
    },
    "num_images": 1,
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "output_format": "png"
}

response = requests.post(
    "https://app.makeugc.ai/api/platform/image-ads/generate",
    headers={"X-Api-Key": os.environ["MAKEUGC_API_KEY"]},
    json=payload,
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"HTTP {response.status_code}: {response.text} "
                       f"(request {response.headers.get('x-request-id')})")
print(response.json())

200 response example

JSON response 
{
  "status": true,
  "data": {
    "id": "job_123",
    "project_id": "project_123",
    "status": "processing"
  }
}

All requests require X-Api-Key. See errors & retries for unsuccessful responses.

Get image ad status #

GET /image-ads/status

Poll data.id. Completed output is an array in data.image_urls.

Parameters

Parameter Description
id
string · query
Required 		id input.

Allowed: At least 1 characters; Up to 256 characters

Request example

cURL 
curl --fail-with-body --max-time 120 -X GET "https://app.makeugc.ai/api/platform/image-ads/status?id=ID" \
  -H "X-Api-Key: $MAKEUGC_API_KEY"
JavaScript 
// Run on your server with Node.js 20+.
const apiKey = process.env.MAKEUGC_API_KEY;
if (!apiKey) throw new Error("Set MAKEUGC_API_KEY first");

const response = await fetch("https://app.makeugc.ai/api/platform/image-ads/status?id=ID", {
  method: "GET",
  headers: {
    "X-Api-Key": apiKey,
  },
  signal: AbortSignal.timeout(120000),
});
const text = await response.text();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${text} (request ${response.headers.get("x-request-id")})`);
}
const result = JSON.parse(text);
console.log(result);
Python 
# Install the requests package before running.
import os
import requests

response = requests.get(
    "https://app.makeugc.ai/api/platform/image-ads/status?id=ID",
    headers={"X-Api-Key": os.environ["MAKEUGC_API_KEY"]},
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"HTTP {response.status_code}: {response.text} "
                       f"(request {response.headers.get('x-request-id')})")
print(response.json())

200 response example

JSON response 
{
  "status": true,
  "data": {
    "id": "job_123",
    "project_id": "project_123",
    "status": "completed",
    "image_urls": [
      "https://your-cdn.example/ad.png"
    ]
  }
}

All requests require X-Api-Key. See errors & retries for unsuccessful responses.