AI product photography API: splash, drip and pour shots

For AI product photography over the Sume API, call one of six catalog image Formats, such as sume-serum-drip or sume-toner-pour, at POST /v1/formats/sume/{slug}/runs with your packshot in attachments. All six are written for beauty and skincare products; for anything else, edit the packshot yourself with POST /v1/images and input_references.

Facts come from the Format catalog, Format API, Structured output, and Image API docs pages, each Format's published description, and the OpenAPI document behind the Sume API reference, read on 2026-09-27.

Which Format makes which shot?

Each description ends “Not for: animated or motion deliverables”, so each Format returns a still. Phrases such as “accurate packaging” state what a Format aims for, not a guarantee, so check every image against the real product. The catalog's other image Formats cover product sets (sume-editorial-product-set), model portraits (sume-model-product-portrait), and magazine covers (sume-magazine-cover-campaign).

How do I call a product-shot Format?

Send the packshot as an input_image attachment with a public HTTPS image_url, from a key with formats:write. To get the image back as a named field, bind an output_schema; the rules are in Sume Format structured output. The docs' example binds hero_image as a SumeMediaFile# next to text fields such as alt_text, and primary_output_key: "hero_image" makes that image the run's primary_output_url.

• Every declared property must be listed in required, so a field the Format may leave empty is a nullable union, like alt_text below. The docs' rule is to require only what the Format actually makes.
• The run answers 202 and takes minutes. Poll it, or set communication.webhook_url for one signed format.run.terminal POST.
• Result media are durable media.sume.com URLs, public to anyone holding them.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-serum-drip/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: serum-30ml-drip-v1" \
  -d '{
    "instruction": "Serum-drip hero image of the attached bottle.",
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/serum-packshot.png" }
    ],
    "output_schema": {
      "name": "acme/serum-hero/v1",
      "strict": true,
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["hero_image", "alt_text"],
        "properties": {
          "hero_image": { "$ref": "SumeMediaFile#" },
          "alt_text": { "type": ["string", "null"] }
        }
      }
    },
    "primary_output_key": "hero_image"
  }'

How do I make a product shot without a Format?

For any other product, send the packshot to POST /v1/images in input_references as a public HTTPS URL, on a model whose input_references descriptor on GET /v1/images/models is not {"min": 0, "max": 0}, and prefer aspect_ratio: "auto" to keep the packshot's shape. Per-model reference limits, sizes, and response fields are in Image generation API with reference images.

How do I cut out or upscale the finished shot?

Two job-backed media tools take a public HTTPS image_url and return Sume-hosted artifacts. RMBG 1.0's schema says to prefer a Sume media URL, such as the Format run's primary_output_url. Poll GET /v1/jobs/:id/status, then read GET /v1/jobs/:id/result. The details are in Remove background API and AI image upscaler API.

What does a product shot cost, and what are the limits?

A Format run's generation is metered at the API pricing rates and capped by generation_spend_cap_usd: up to $500, null runs at $500, 0 is rejected, and omitting it inherits the Format's cap. The run's full cost, the agent's own LLM turn included, is usage.debited_usd_micros. On the direct path, image billing is all-or-nothing: a completed image is billed in full and a failed one is not billed.

• Attachments: JPEG, PNG, WebP, GIF, or AVIF, up to 30 MB each, and up to 30 images and 500 MB per run.
• No model choice inside a Format run: the run's model field picks only the orchestrating LLM, and the Format's tools choose the image models.