Text to image

Generate an image from a prompt. Like every PierNode generation, this is asynchronous: you start a task and poll it until it reaches a terminal state.

POST /api/v1/images/generations

curl -X POST https://your-piernode-host/api/v1/images/generations \
  -H "Authorization: Bearer $PIERNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a red ceramic teapot on a wooden table", "resolution": "1k", "aspectRatio": "1:1"}'

Request

Field	Type	Required	Default	Notes
`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`.
`aspectRatio`	string	no	`1:1`	`1:1`, `9:16`, `16:9`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`, `1:2`.

Request bodies are limited to 64 KB. Any field not listed above is ignored.

Response

Returns as soon as the task is accepted — not when the image is ready.

{
	"id": "the-task-id",
	"status": "QUEUED",
	"createdAt": "..."
}

What it costs

Images are priced per image, per resolution tier. One request produces one image, so a request costs exactly that tier's rate. Aspect ratio does not affect the price.

Not every tier is necessarily on sale. A resolution without a configured price returns 503 and nothing is reserved — there is no fallback rate and you are never charged for a configuration PierNode does not sell.

The cost is reserved from your balance when the task is accepted, and returned in full if the generation does not succeed.

Getting the result

Poll GET /api/v1/tasks/{taskId}, the same endpoint used by every generation type. On success the task carries:

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

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

Polling is not billed.

Errors

Code	Meaning
`INVALID_INPUT`	The request was rejected and will not succeed if retried.
`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.
`NO_PROVIDER_CONFIGURED`	This task type cannot currently be run.

A task that does not succeed returns its reservation to your balance.

Cancelling

POST /api/v1/tasks/{taskId}/cancel cancels a task that has not started running. Once a generation is in flight it responds with 409.