API reference

Every endpoint of the PopNow API on one page, with links to the full OpenAPI contract.

The complete, machine-readable contract is openapi.yaml (OpenAPI 3.1). Import it into Postman, Insomnia or a code generator, or hand it to an AI agent. This page is the human-sized map.

Base URL: https://api.popnow.ai/api/v1 (OpenAI-compatible routes: https://api.popnow.ai/v1)
Authentication: Authorization: Bearer sk-popnow-… on every request
Envelope: { "code", "msg", "data", "request_id" }; code: 200 is success
Amounts: whole credits (credits, maxCredits …), each also given as a US dollar string; 1 credit = $0.01

Tasks

Method and path	Does	Page
`POST /jobs/createTask`	Create a generation task (optional `?wait=` up to 60 s)	Tasks
`GET /jobs/recordInfo?taskId=`	Read a task's state and result	Tasks
`GET /jobs`	List this key's tasks	Tasks
`POST /jobs/quote`	Price a request without running it	Billing
`POST /jobs/retry`	New task from a failed or expired one	Tasks
`POST /jobs/purge`	Delete a finished task's content	Tasks

Models

Method and path	Does	Page
`GET /models`	Every callable model with prices (`?includeSchema=1` for input schemas)	Models
`GET /models/{model}`	One model, including its input schema	Models

Files and assets

Method and path	Does	Page
`POST /common/upload-url`	Ticket for a direct upload	Media
`POST /files/{fileId}/commit`	Finish an upload and get its `popnow://` URI	Media
`POST /files/import`	Import a LoRA file from a link	Assets
`POST /common/download-url`	Fresh signed link to a task's output	Media
`GET /assets`, `POST /assets`	List or save assets	Assets
`GET`, `PATCH`, `DELETE /assets/{assetId}`	Read, rename or delete one asset	Assets
`GET /assets/entities`	Your characters	Assets
`GET /assets/usage`	Storage plan and usage	Assets

Account

Method and path	Does	Page
`GET /chat/credit`	Balance: available, held, total	Billing
`GET /usage`	This key's usage by day and by model	Billing

OpenAI Videos compatible (`/v1`)

Method and path	Does	Page
`POST /v1/videos`	Create a video task	OpenAI Videos
`GET /v1/videos/{id}`	Read it	OpenAI Videos
`GET /v1/videos/{id}/content`	Redirect to the file	OpenAI Videos
`GET /v1/models`	Model list in OpenAI's shape	OpenAI Videos

Common headers

Header	Direction	Meaning
`Idempotency-Key`	Request	Makes retries of a write safe for 24 hours (Idempotency)
`Accept-Language`	Request	Language of error messages (Errors)
`X-PopNow-Retention`	Request	Shorten how long one task's content is kept, in seconds
`X-Request-Id`	Response	Same as `request_id`; quote it to support
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`	Response	Rate limits (Rate limits)