Get a generation: GET /v1/generations/{id}

GET https://api.percify.io/v3/playground/v1/generations/{id} returns the current state of a generation you started with POST /v1/run. When status is succeeded, the files are in output.urls. Add ?wait=45 and Percify holds the request open until the run finishes or 45 seconds pass, so you need fewer calls.

GET https://api.percify.io/v3/playground/v1/generations/{id}?wait=45
Authorization: Bearer pk_live_…

Parameters

string

required

The generation id (a UUID) from POST /v1/run. You can only read generations from your own account.

integer

Seconds to wait on the server for the run to finish, from 5 to 55. Values outside that range are clamped. Leave it out to get the current state immediately.

Response

string

The generation id.

string

The model that ran.

string

processing, succeeded or failed. See statuses.

object | null

Set when status is succeeded: type is image, video or audio, and urls is an array of file URLs on cdn.percify.io.

string | null

Why the run failed, when status is failed.

integer

Credits charged when the run started. On a failed run the same amount was refunded to your balance.

string

When the run started.

number | null

Length in seconds of the input audio or video that a duration-billed model was priced on, such as lip-sync. null for other models.

boolean

Only present with wait: true when the wait ended before the run did. Call again.

input and completedAt also appear in the object and are null on this endpoint.

Example: wait for the result

curl -s "https://api.percify.io/v3/playground/v1/generations/3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83?wait=45" \
  -H "Authorization: Bearer $PERCIFY_API_TOKEN"

const API = "https://api.percify.io/v3/playground/v1";
const headers = { Authorization: `Bearer ${process.env.PERCIFY_API_TOKEN}` };

async function waitForGeneration(id) {
  for (;;) {
    const res = await fetch(`${API}/generations/${id}?wait=45`, { headers });
    const { data } = await res.json();
    if (data.status === "succeeded") return data.output.urls;
    if (data.status === "failed") throw new Error(data.error);
  }
}

console.log(await waitForGeneration("3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83"));

import os, requests

API = "https://api.percify.io/v3/playground/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PERCIFY_API_TOKEN']}"}

def wait_for_generation(gen_id):
    while True:
        data = requests.get(f"{API}/generations/{gen_id}", params={"wait": 45},
                            headers=HEADERS, timeout=70).json()["data"]
        if data["status"] == "succeeded":
            return data["output"]["urls"]
        if data["status"] == "failed":
            raise RuntimeError(data["error"])

print(wait_for_generation("3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83"))

Succeeded

{
  "success": true,
  "data": {
    "id": "3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83",
    "modelId": "gpt-image-2",
    "status": "succeeded",
    "input": null,
    "output": {
      "type": "image",
      "urls": ["https://cdn.percify.io/media-assets/playground/3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83-0"]
    },
    "error": null,
    "creditsSpent": 4,
    "createdAt": "2026-09-16T09:41:07.512Z",
    "completedAt": null,
    "mediaDurationSec": null
  }
}

Still running after the wait

{
  "success": true,
  "data": {
    "id": "3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83",
    "modelId": "gpt-image-2",
    "status": "processing",
    "input": null,
    "output": null,
    "error": null,
    "creditsSpent": 4,
    "createdAt": "2026-09-16T09:41:07.512Z",
    "completedAt": null,
    "mediaDurationSec": null,
    "stillRunning": true
  }
}

Errors

Status	Message starts with	Cause
`400`	`Invalid generation id`	The id is not a UUID. Use the `id` from `POST /v1/run`.
`401`	`Invalid, expired, or revoked API key`	See Authentication.
`404`	`Generation not found`	No generation with this id exists in the account that owns the key.
`429`	`API key rate limit exceeded`	More than 60 requests a minute on this key.

Tips

Save the files you need. output.urls point to cdn.percify.io, and your own storage is the copy you control.
Set your HTTP client timeout above the wait value, for example 70 seconds for wait=45.
Every poll counts toward the 60 requests a minute per key. wait=45 keeps a single job to about one request a minute.
For long lip-sync videos, a webhook saves you from polling at all.

Async jobs and polling

Statuses, time limits and refunds.

Start a generation

The call that returns the id.

Webhooks

Get the finished result pushed to you.

Errors and rate limits

Every status code.

Get started

Generations

Async and webhooks

Build with the API

Account

MCP

Get a generation: GET /v1/generations/{id}

Parameters

Response

Example: wait for the result

Errors

Tips

Async jobs and polling

Start a generation

Webhooks

Errors and rate limits

​Parameters

​Response

​Example: wait for the result

​Errors

​Tips

​Related

Async jobs and polling

Start a generation

Webhooks

Errors and rate limits

Parameters

Response

Example: wait for the result

Errors

Tips

Related