Suede x402 API endpoints

Three endpoints, one payment rail. Each is a POST to https://app.suedeai.ai, priced per call in USDC on Base, and a paid call returns a job you can poll for free. The figures below come from the live discovery document and OpenAPI spec, checked on 2026-10-11.

The three paid endpoints

Endpoint	What you get	Price	amount	Poll route
`POST /create-music`	A complete original song with vocals, melody and full arrangement, as a finished MP3	$0.50	`500000`	`GET /api/songs/{songId}`
`POST /agent/video`	An 8-second 720p clip with native audio	$4.99	`4990000`	`GET /agent/video/{jobId}`
`POST /agent/image`	One hosted still image, PNG or JPEG	$0.15	`150000`	`GET /agent/image/{jobId}`

amount is the price in USDC base units (6 decimals), exactly as it appears in the 402 challenge and the value you sign. Each endpoint takes a JSON body in which prompt is the only required field.

Payment terms shared by all three

Field	Value
`x402Version`	`2`
`scheme`	`exact`
`network`	`eip155:8453` (Base mainnet)
`asset`	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (USDC; EIP-712 domain `"USD Coin"`, version `"2"`)
`payTo`	`0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F`
`maxTimeoutSeconds`	`300`

The same PAYMENT-SIGNATURE header also accepts Skyfire pay+jwt and kya-pay+jwt tokens. The product catalog lists Stripe Checkout as a second payment method at the same USD prices: 50, 499 and 15 cents. The quickstart walks through the x402 payment step by step.

Request headers

Header	Required	Use
`Content-Type: application/json`	Yes	All three endpoints take a JSON body.
`PAYMENT-SIGNATURE`	For a paid call	A base64 x402 `PaymentPayload` or a Skyfire token. Leave it off the first call to receive the 402 challenge.
`X-Idempotency-Key`	No	Up to 200 characters. Resending the same key and body within the cache window returns the original response without charging again.
`Suede-API-Version`	No	Pins the API version. The current and only supported value is `1`.

Asynchronous by default

A call that carries PAYMENT-SIGNATURE queues the job and answers 202 Accepted with a pollUrl. Renders take minutes, and x402 and Skyfire clients time out in about 30 seconds, so this keeps your payment client from timing out mid-render. Polling needs no further payment.

?async=false forces a blocking call that answers 200 with the finished asset.
?async=true queues the job. Only the literal true selects asynchronous mode; 1, yes and on count as false.
The body field asyncMode can switch asynchronous mode on, never off. "asyncMode": false leaves a paid call asynchronous.

All three endpoints answer 202 for a queued job, so a 2xx other than 202 means the asset is already in the body.

Response codes

Status	Meaning
`202`	Paid call accepted and queued. Poll `pollUrl`.
`200`	Blocking call finished, with the asset in the body.
`400`	Bad request, for example an unsupported `Suede-API-Version`.
`402`	Payment required, or the payment was not accepted.
`422`	The body failed validation. A paid request that fails validation is not charged.
`429`	Rate-limited. Wait for `Retry-After`.
`5XX`	Server or upstream failure. Not charged; retry with the same `X-Idempotency-Key`.

Bodies, headers and retry rules for each code are on the errors page.

Sources

app.suedeai.ai/.well-known/x402: resources, prices and payment requirements.
app.suedeai.ai/openapi.json: headers, the async parameter and response codes.
app.suedeai.ai/api/v1/catalog: product descriptions and payment methods.

For every machine-readable format these endpoints are published in, see discovery documents and MCP server.