Get the edited image URL as a named field from an Agent Completion

Send the photo in attachments and an output_schema in the same POST /v1/agent/completions call. The images go to the agent, and when the run completes Sume parses output against your schema, so you can ask for fields like edited_url and changes instead of scraping text.

What the docs promise

The Agent Completions page says attachments and output_schema can be used together: the images go to the agent, and after the run completes Sume still parses the output against your schema (Agent Completions). A turn that only has images is allowed. Without a text part, the agent is told to use the attached files.

A schema for an edit

Ask for the URL and a short list of what changed. The agent fills the URL from the media it generated, and your code checks it before it uses it.

payload = {
    "instruction": "Replace the grey wall with warm white. Keep everything else.",
    "attachments": [{"type": "input_image", "image_url": "https://example.com/room.jpg"}],
    "output_schema": {
        "name": "edit_result",
        "schema": {
            "type": "object",
            "properties": {
                "edited_url": {"type": "string"},
                "changes": {"type": "array", "items": {"type": "string"}},
            },
            "required": ["edited_url", "changes"],
            "additionalProperties": False,
        },
    },
    "generation_spend_cap_usd": 1,
}

Check what you get back

Poll GET /v1/agent-runs/{id} until the run is completed. The generated files are also in output.images, so compare the URL in your field with that list. A URL in edited_url that is not in output.images is a sign the agent wrote something it did not generate, and you should treat the run as failed.

When not to use it

If all you need is one URL back, the Image API already returns data[].url and needs no schema. A schema is useful when the task has more than one output, for example an edited image, a list of changes and a flag for whether the logo stayed untouched. Remember that the agent's own report of a change is not proof of it: diff the images before you trust the changes list.

Handling the failure cases

A run can finish as failed or canceled, and then your schema does not apply. Check the status first. If a run fails after spending on a generation, the cap is what bounds the loss, so choose it for the task and not as a round number.

Send an Idempotency-Key so a client retry after a timeout gets the original receipt and does not start a second run. If you send the same key with a different payload, you get a 409 and should fix the caller.