Quickstart

Five steps, one of which is waiting.

1. Create an API key

Open the API key section of your dashboard and generate one. It is shown once — copy it before leaving the page.

export PIERNODE_API_KEY="pn_..."

Check it works:

curl https://app.piernode.com/api/v1/me \
  -H "Authorization: Bearer $PIERNODE_API_KEY"

2. Add funds

Generations are paid from a USD balance on your account. Top it up from the Add funds section of the dashboard. A 1K image costs a fraction of a cent, so a small deposit goes a long way while you are testing.

Without a balance, generation requests return 402.

3. Start a generation

curl -X POST https://app.piernode.com/api/v1/images/generations \
  -H "Authorization: Bearer $PIERNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a red ceramic mug on a wooden table, studio lighting"}'

It returns immediately with a task, not an image:

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

The cost is reserved from your balance at this point.

4. Poll the task

curl https://app.piernode.com/api/v1/tasks/01JD8Z9K2M4N6P8Q0R2S4T6V8W \
  -H "Authorization: Bearer $PIERNODE_API_KEY"

Keep polling every few seconds while status is QUEUED or PROCESSING. Polling is free. An image usually takes under two minutes; video takes longer.

5. Download the result

When status is SUCCEEDED:

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

Download the file. The link is valid for one hour — re-poll the task for a fresh one, or copy the file somewhere of your own.

Where next

• Uploading an image — required for image-to-image and image-to-video.
• Tasks — statuses, results and cancellation.
• Errors — what each status code means.