From key to first render: what should I watch out for?

Jobs are queued, not instant. A 202 means accepted — the asset URL arrives on the job, not the create call.

From key to first render: what should I watch out for?

Project format is immutable after the first take. Changing aspect means a new project, on purpose.

GETTING STARTED

From key to first render

Three calls. A key, a project, a shot. Everything else in these docs is a refinement of this loop.

THE LOOP

01KeyOne credential covers generation, editing and webhooks.

02ProjectA container with a format, an aspect and a look.

03ShootGenerate against a shot, not a bare prompt string.

04DeliverAssemble selected takes and export per platform.

Every later feature plugs into this same four-step shape — nothing you learn here gets thrown away.

Calls

POST /v1/projects: Create a project. Returns the project ID everything else cites.
POST /v1/shots: Add a shot to the board with cast, location and duration.
POST /v1/shots/{id}/takes: Generate. Async — poll the job or register a webhook.
POST /v1/deliver: Assemble the selected takes into platform masters.

RequestPOST /v1/projects

{
  "title": "Cold Brew launch",
  "format": "9:16",
  "duration": 30
}

Response200 OK

{
  "id": "prj_4a81b",
  "board": [],
  "look": null
}

From the CLI

$ npm install picx-ai
$ npx picx-ai login
$ npx picx-ai init "Cold Brew launch" --format 9:16

✓ prj_4a81b created

For users

You do not need to understand the graph to start. Create a project, describe a shot, hit generate — the structure fills itself in behind you.

For developers

Everything is async and idempotent. Pass an Idempotency-Key header on any POST that spends money; a retry with the same key returns the original job rather than charging twice.

Gotchas

Jobs are queued, not instant. A 202 means accepted — the asset URL arrives on the job, not the create call.
Project format is immutable after the first take. Changing aspect means a new project, on purpose.