API reference

Base URL: https://app.piernode.com

Every endpoint takes Authorization: Bearer pn_... except the two public ones. See Authentication.

A machine-readable OpenAPI document for everything below is served at https://app.piernode.com/api/spec.json, with a browsable version at /api/docs.

Generation

The two transformation endpoints also accept effectId in place of a prompt — see effects.

All four return a task immediately and reserve the cost. Poll for the result.

All four accept an optional Idempotency-Key header, which makes a submission safe to retry — see idempotency. It is not accepted anywhere else, because nowhere else spends money.

Public

No key, no account.

Tasks

Uploads

Not billed. See Uploading an image.

Account

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

{
	"id": "the-account-id",
	"balance": "100.000000",
	"currency": "USD"
}

Conventions

Shared by every endpoint:

• Request bodies are JSON, limited to 64 KB. Unknown fields are ignored.
• Amounts are exact decimal strings, never floating-point numbers.
• Timestamps are ISO 8601 in UTC.
• Ids are opaque strings. Task ids are 24 lowercase alphanumeric characters and upload ids are 32 hex characters today, but treat both as opaque text of up to 64 characters rather than parsing or sizing to the current format.
• Enum values are lowercase (720p, hd, 16:9).
• Errors carry a status code, a stable code, a human-readable message and a requestId — see Errors.
• Every response carries an X-Request-Id header. Send your own to have it echoed back, so your logs and ours line up.
• A generation answered from an Idempotency-Key carries Idempotency-Replayed: true.
• Generation requests are limited to 60 per minute per account, across all four generation endpoints.