Combine

Combine merges 2–5 images into one output. A prompt describes how to arrange them.

depicta uvx depicta npx depicta

Usage

depicta combine image hero.png sidebar.png --prompt "Place hero on the left, sidebar on the right"

The API takes the input images as HTTPS URLs (input_image_urls, 2–5 entries). Upload local files first with POST /v1/upload; the CLI does this for you.

curl

# Upload each local file first (repeat per file) and note its upload_url
curl -X POST https://api.depicta.ai/v1/upload \
  -H "Authorization: Bearer dpct_YOUR_API_KEY" \
  -F "image=@hero.png"

curl -X POST https://api.depicta.ai/v1/combine/image \
  -H "Authorization: Bearer dpct_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 900 \
  -d '{"input_image_urls": ["HERO_UPLOAD_URL", "SIDEBAR_UPLOAD_URL"], "prompt": "Place hero on the left, sidebar on the right"}'

Python

import httpx

headers = {"Authorization": "Bearer dpct_YOUR_API_KEY"}

def upload(path):
    with open(path, "rb") as f:
        return httpx.post(
            "https://api.depicta.ai/v1/upload", headers=headers, files={"image": f}
        ).json()["upload_url"]

response = httpx.post(
    "https://api.depicta.ai/v1/combine/image",
    headers=headers,
    json={
        "input_image_urls": [upload("hero.png"), upload("sidebar.png")],
        "prompt": "Place hero on the left, sidebar on the right",
    },
    timeout=900,  # generations can take several minutes
)

Content types

Like generate and edit, combine is type-specific:

Endpoint	Use for
POST /v1/combine/image	Photos, illustrations
POST /v1/combine/graphic	Icons, logos, UI elements
POST /v1/combine/diagram	Merge diagram sections

Reference images

Combine also supports up to 5 reference images to guide the composition style — for example, showing how elements should be arranged or what visual tone to aim for.

See Generate — Reference images for full details.

Limits

• Minimum: 2 images
• Maximum: 5 images. Some models take fewer (max_combine_inputs in GET /v1/models); sending more returns 422 validation_error with the model’s limit, and nothing is charged.
• Each image can be a file, URL, or stdin (CLI) or an HTTPS URL (API)
• Without --model, combine uses your default model if it can combine, otherwise gemini
• mai and mai-fast cannot combine. See Models

Response

Same format as generate.