API reference

The API is served under /api. Every endpoint requires an API key.

Generation is asynchronous: you start a task, then poll it until it reaches a terminal state.

POST /api/v1/videos/generations

Starts a video generation from a text prompt.

curl -X POST https://your-piernode-host/api/v1/videos/generations \
  -H "Authorization: Bearer $PIERNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a calm sea at dawn", "resolution": "720p", "aspectRatio": "16:9", "durationSeconds": 5}'

Request

Field	Type	Required	Default	Notes
`prompt`	string	yes	—	1–2000 characters.
`resolution`	string	no	`720p`	`480p`, `512p`, `720p`, `1080p`.
`aspectRatio`	string	no	`16:9`	`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`.
`durationSeconds`	int	no	`5`	4–15.

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 video is ready.

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

The cost is reserved from your balance when the task is accepted, and returned in full if the generation does not succeed. A request with too little balance is rejected with 402 and nothing is reserved.

GET /api/v1/tasks/{taskId}

Returns the current state of one of your tasks. You may only fetch your own tasks; another account's task id responds exactly like one that does not exist.

{
	"id": "...",
	"type": "video.generate",
	"status": "SUCCEEDED",
	"createdAt": "...",
	"startedAt": "...",
	"completedAt": "...",
	"output": {
		"videos": [{ "url": "https://...", "contentType": "video/mp4", "sizeBytes": 1048576 }]
	},
	"error": null
}

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

Statuses

Status	Meaning
`QUEUED`	Accepted and waiting to run.
`PROCESSING`	Currently running.
`SUCCEEDED`	Finished. `output` carries the result.
`FAILED`	Did not finish. `error` carries a code and message.
`CANCELLED`	Cancelled before it started.

SUCCEEDED, FAILED and CANCELLED are terminal. When a task does not succeed, whatever was reserved for it is returned to your balance.

Polling is not billed. Poll as often as you reasonably need.

Errors

Code	Meaning
`INVALID_INPUT`	The request was rejected and will not succeed if retried.
`GENERATION_FAILED`	The generation ran but did not produce a result.
`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.
`WORKER_TIMEOUT`	The task exceeded its attempt limit.

POST /api/v1/tasks/{taskId}/cancel

Cancels a task that has not started running and returns its reservation.

{ "id": "...", "status": "CANCELLED" }

Only a QUEUED task can be cancelled. Once a generation has started it responds with 409 — PierNode does not promise to recall work that is already running.

GET /api/v1/me

Returns the account the presented API key belongs to, and its balance.

Field	Type	Description
`id`	string	Identifier of the account owning the key.
`balance`	string	Available balance, as an exact decimal string.
`currency`	string	Currency of the balance. Always `USD` today.

balance is a string rather than a number so exact decimal amounts survive JSON parsing without floating-point rounding.

On this page