Image generation API with reference images: POST /v1/images

To generate an image from reference images with Sume, send POST /v1/images with a model, a prompt, and an input_references array of public HTTPS image URLs. Use a catalog model id to select a family, or send model: "sume/auto" to let Image Router choose. The call waits up to 30 seconds, and most catalog models finish inside that budget.

Every detail below comes from the Image API docs, with notes from the Image 1.0 page.

How do I send reference images?

Add each image as an input_references entry of type image_url. This is the docs' image-to-image example as a cURL call:

• Reference URLs must be public HTTPS. Localhost, private-network, and non-HTTPS URLs are rejected before submission.
• A model whose input_references descriptor is {"min": 0, "max": 0} is text-to-image only and rejects references.
• On edit and image-to-image calls, prefer aspect_ratio: "auto" to match the reference. Omitting the field is not the same as auto.

curl -X POST "https://api.sume.com/v1/images" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "make this scene look like a watercolor painting",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
    ]
  }'

How many reference images can a model take?

It depends on the model, and the catalog says so before you call. GET /v1/images/models lists each model's supported_parameters; GET /v1/images/models/{model_id}/endpoints returns the definitive set plus pricing. Parameters use typed descriptors: enum (an allowlist), range (an integer between min and max), and boolean. A request that sets a parameter the model does not list is rejected with 400 unsupported_parameter rather than silently dropped.

One example from the docs: ChatGPT Image 2.5 (openai/gpt-image-2.5 and openai/gpt-image-2.5-sunburst) supports text-to-image, up to 16 image references, an optional mask_url, and background: auto|transparent|opaque. For transparent stills today, the docs point to Image 1.0 with transparency: true.

Which fields can I send?

Should I pin a model or send sume/auto?

sume/auto is a Sume-only value. Sume picks the family and never discloses which one ran: sume/auto is not listed in GET /v1/images/models, and both the response model and job.model stay sume/auto. Bare Image Router ids such as gpt-image-2 and nano-banana-2 are accepted as aliases for their org/slug equivalents.

Image 1.0 is retiring soon, and its URLs remain compatibility aliases for the same Auto pipe; there, references go in image_urls (1–10 public HTTPS URLs). The move is covered in Video 1.0 and Image 1.0 to sume/auto.

What comes back, and what if it takes longer?

A finished call returns 200 with data[].url, a Sume-hosted signed URL rather than inline base64, and usage.cost, the USD amount billed to your wallet. Token counts are always 0 in v1.

If the image is still generating when the 30-second budget expires, or you send mode: "async" or mode: "webhook" with a webhook_url, Sume returns 202 with the standard job envelope. Poll GET /v1/jobs/{id}/status, then fetch GET /v1/jobs/{id}/result. Branch on the status code, not the body shape. Slow configurations such as 4K, high quality, or a large n are the most likely to return 202.

What does the Image API not support yet?

The docs list these gaps in v1:

• Streaming. stream: true returns 400 streaming_not_supported. For progress, submit with mode: "async" and read GET /v1/jobs/:id/events; mode: "subscribe" is an alias of sync, not a progress stream.
• seed, output_compression, and explicit pixel size. They are in the schema, but no model advertises them, so each returns 400 unsupported_parameter.
• Provider choice. provider.options must be omitted or empty, only and order accept only "sume", and any other slug returns 400 provider_not_available.

How is image generation billed?

Billing is all-or-nothing. A completed generation is billed in full at the endpoint's pricing. A failed or cancelled generation is not billed, and failed requests return 502 Bad Gateway; a client that disconnects early is billed as a failed generation, which means not at all. Endpoint pricing lines already include Sume's margin, so cost_usd × n is what you pay. Current rates are on API pricing.