Generate Image

Turn a prompt into an image. The request returns a task; the image arrives when you poll it.

Minimal request

curl -X POST https://app.piernode.com/api/v1/images/generations \
  -H "Authorization: Bearer $PIERNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"prompt": "a red ceramic teapot on a wooden table"}'

{
	"id": "fu0825tesv0laouebtjx0x5w",
	"status": "QUEUED",
	"createdAt": "2026-01-01T12:00:00.000Z"
}

The cost is reserved at this point. Nothing else is needed — every other field has a default.

Parameters

Field	Type	Required	Default	Description
`prompt`	string	yes	—	1–2000 characters.
`negativePrompt`	string	no	—	Up to 1000 characters. What to steer away from.
`resolution`	string	no	`1k`	`1k`, `2k`, `4k`. Sets the price.
`aspectRatio`	string	no	`1:1`	`1:1`, `9:16`, `16:9`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`, `1:2`.

Aspect ratio does not affect the price. Bodies are limited to 64 KB, and any field not listed is ignored.

A fuller example

curl -X POST https://app.piernode.com/api/v1/images/generations \
  -H "Authorization: Bearer $PIERNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "prompt": "a red ceramic teapot on a wooden table, studio lighting",
    "negativePrompt": "blurry, text, watermark",
    "resolution": "2k",
    "aspectRatio": "16:9"
  }'

Getting the result

Poll the task. On success:

{
	"status": "SUCCEEDED",
	"output": {
		"images": [{ "url": "https://...", "contentType": "image/png", "sizeBytes": 576963 }]
	}
}

Result links are signed and expire after an hour. Poll again for a fresh one — the stored image itself does not expire.

Errors

Status codes are listed in errors. A task that fails carries one of these in error.code:

Code	Meaning
`GENERATION_FAILED`	The generation ran but produced no usable image.
`PROVIDER_OUTPUT_INVALID`	A result came back that could not be stored.
`PROVIDER_UNAVAILABLE`	The generation service could not be reached.
`PROVIDER_SUBMIT_AMBIGUOUS`	The generation could not be confirmed and was not retried.
`GENERATION_TIMED_OUT`	It did not finish in time.
`NO_PROVIDER_CONFIGURED`	This task type cannot currently be run.

Any of them releases the reservation in full.

Minimal request

Parameters

A fuller example

Getting the result

Errors

See also

On this page