Polling a task

Every generation returns a task straight away and does the work afterwards. You collect the result by polling the same endpoint, whatever was generated.

GET /api/v1/tasks/{taskId}

curl https://app.piernode.com/api/v1/tasks/\{taskId\} \
  -H "Authorization: Bearer $PIERNODE_API_KEY"

Polling is not billed, but it is rude to hammer it. Wait a couple of seconds after submitting, then poll every few seconds, and back off if a task is taking a while — video takes considerably longer than images, and higher resolutions longer than lower ones. Stop as soon as the status is SUCCEEDED, FAILED or CANCELLED; those never change again.

We publish no completion-time guarantee. A task that stops making progress is failed on its own and its reservation released, so a poll loop does not need its own timeout to avoid waiting forever — but give it a generous ceiling anyway and surface the task id if it trips.

Statuses

QUEUED and PROCESSING are the only non-final states. Once a task reaches any of the other three it never changes again.

Results

Images come back under images:

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

Videos come back under videos, in the same shape:

{
	"status": "SUCCEEDED",
	"output": {
		"videos": [{ "url": "https://...", "contentType": "video/mp4", "sizeBytes": 8388608 }]
	}
}

Only the key that applies is present, so check for the one you expect.

Result links expire

A result url is valid for one hour. Polling the task again mints a fresh one, so a link going stale is never a lost result — but if you need the file long-term, copy it into your own storage.

Failures

{
	"status": "FAILED",
	"output": null,
	"error": {
		"code": "GENERATION_FAILED",
		"message": "The generation did not complete successfully."
	}
}

The reservation is released back to your balance when a task fails. You are not charged for work that produced nothing.