Edit a photo with an Agent Completion: attach it, read output.images

To edit a photo with an Agent Completion, send the instruction and the photo in attachments to POST /v1/agent/completions with a generation_spend_cap_usd, poll the run, and read the result from output.images. The agent looks at the image, picks its own tool for the edit, and stays under your cap. It is a different shape from POST /v1/images, where you pick the model and parameters yourself.

The request

The call returns 202 and an agent.run receipt. Each attachment is an input_image with either an image_url or an asset_id. You can send up to 30 images, 30 MB each and 500 MB per run, in JPEG, PNG, WebP, GIF or AVIF (Agent Completions, Formats). generation_spend_cap_usd has no default and a missing field is a 400.

import os, time, requests

H = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}
r = requests.post(
    "https://api.sume.com/v1/agent/completions",
    headers=H,
    json={
        "instruction": "Remove dust specks from this product photo. Keep the product and label unchanged.",
        "attachments": [{"type": "input_image", "image_url": "https://example.com/shot.jpg"}],
        "generation_spend_cap_usd": 1,
    },
    timeout=60,
)
r.raise_for_status()
run = r.json()["data"]
while True:
    s = requests.get(f"https://api.sume.com/v1/agent-runs/{run['id']}", headers=H, timeout=60).json()
    s = s.get("data", s)
    if s["status"] in ("completed", "failed", "canceled"):
        break
    time.sleep(5)
print(s["status"], (s.get("output") or {}).get("images"))

What comes back

A completed run has output.text for the agent's last message and output.images for generated pictures, with durable media.sume.com URLs. The run also records spend in usage. A failed or canceled status ends the loop in the code above, so check the status before you read the images.

Errors to expect

invalid_attachment is a bad item, attachment_too_large is a 413, attachment_fetch_failed is a 502 that means Sume could not download your URL, and insufficient_scope is a 403 for a key without the right scope. Re-sending with the same Idempotency-Key returns the original receipt, and a different payload under the same key is a 409.

When not to use it

If you already know the model, the aspect ratio and the exact prompt, use the Image API. It is synchronous for up to 30 seconds, you can set quality and aspect_ratio. A completion is better when the task is loose, for example a photo plus a written brief where the agent should choose between a retouch and a background change.

Also keep the cap honest. The agent can make several generation calls in one run, so a cap of $1 is the most you accept for the whole task, not for one image.

A note on cost

The cap is the control you have. Sume documents the metered rates on the API pricing page, and a good habit is to run one example with a generous cap, read usage on the finished run, and set later caps a little above that figure.

If a run ends as failed, read the status payload before you retry. A retry with the same Idempotency-Key returns the original receipt, so use a new key only when you mean to start a new run.