Agent Image: POST /agent/image

Generate one hosted still image from a text prompt, as PNG or JPEG. One call costs $0.15 in USDC on Base, the lowest price of the three endpoints, which also makes it the cheapest way to test a full payment round trip.

What it is for

Album and single cover art, podcast and video thumbnails, social and campaign graphics, concept art, storyboard frames, product shots and article illustrations. Frame it square, portrait or widescreen.

At a glance

Endpoint	`POST https://app.suedeai.ai/agent/image`
Price	$0.15, `amount` `150000` USDC base units
Payment	x402 `exact` on `eip155:8453` to `0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F`, or a Skyfire token
Output	One hosted PNG or JPEG
Paid response	`202 Accepted` with `jobId` and `pollUrl`
Poll	`GET https://app.suedeai.ai/agent/image/{jobId}`, free
Identifiers	OpenAPI `operationId`, A2A skill and MCP tool: `agent_image`

Request body

Field	Type	Required	Description
`prompt`	string	Yes	Visual prompt describing the image to generate.
`aspectRatio`	string	No	One of `1:1`, `9:16`, `16:9`, `3:4`, `4:3`, `3:2`, `2:3`, `5:4`, `4:5`, `21:9`.
`outputFormat`	string	No	`png` or `jpeg`.
`asyncMode`	boolean	No	Switches asynchronous mode on, never off. Paid calls are already asynchronous.

The ten aspect ratios cover square (1:1), portrait (4:5, 3:4, 2:3, 9:16) and landscape or widescreen (5:4, 4:3, 3:2, 16:9, 21:9) framing.

Example: square cover art

Get the 402 challenge first (amount 150000, priceUsd $0.15), sign it as shown in the quickstart, then send:

curl -i -X POST https://app.suedeai.ai/agent/image \
  -H 'Content-Type: application/json' \
  -H "PAYMENT-SIGNATURE: $PAYMENT" \
  -H 'X-Idempotency-Key: cover-art-0001' \
  -d '{
    "prompt": "Album cover, neon city at night, rain on glass",
    "aspectRatio": "1:1",
    "outputFormat": "png"
  }'

Response to a paid call: 202 Accepted

The discovery document gives this example body:

{
  "jobId": "image-job-example",
  "status": "queued",
  "provider": "suede",
  "pollUrl": "https://app.suedeai.ai/agent/image/image-job-example"
}

With ?async=false the call blocks and answers 200 with the same body shape as the poll below.

Polling: GET /agent/image/{jobId}

Poll until status is completed, with imageUrl set, or failed. Both are final; queued and processing mean poll again.

Field	Description
`jobId`	The render's job identifier.
`status`	`queued`, `processing`, `completed` or `failed`.
`provider`	The provider handling the render.
`imageUrl`	The generated image once complete; `null` until then.
`pollUrl`	Set on the 202 accept; `null` on a poll response.

An unknown or expired jobId answers 200 with status failed, not 404. On 2026-10-11 that response looked like this:

{"jobId":"unknown-job-id","imageUrl":null,"status":"failed","provider":"suede","pollUrl":null,"error":"Generation failed. Please try again."}

A polling loop in Python

import time
import httpx

def wait_for_image(poll_url: str) -> str | None:
    while True:
        job = httpx.get(poll_url).json()
        if job["status"] == "completed":
            return job["imageUrl"]
        if job["status"] == "failed":
            return None
        time.sleep(5)

The suede-ai SDK handles the payment and returns the pollUrl this loop needs.

Sources

app.suedeai.ai/.well-known/x402: description, price, payment requirement, input schema and example output (resource entry last updated 2026-08-30).
app.suedeai.ai/openapi.json: operations agent_image and agent_image_status.
Live requests on 2026-10-11: the unpaid 402 challenge and a poll for an unknown jobId.