Picverce AI just shipped a Public API so you can run the same image tools and generation models from your own backend, not only from picverce.com.
Base URL:
https://api.picverce.com
OpenAPI contract:
https://picverce.com/openapi-v1.yaml
Human docs:
https://picverce.com/api-docs/
Create keys in Account → API Keys:
https://picverce.com/account/?tab=api
This post is a developer walkthrough of what is live today, how jobs work, which Tools and Models you can call, and how credits + access work.
Picverce AI is a bilingual (EN/ES) studio of image tools: enhance, upscale, restore, colorize, background remove, photo-to-anime, hairstyle, outfit, and a full Generate workspace with many models.
Partners kept asking for the same capabilities behind a clean HTTP API:
Public API v1.0.0 is that surface.
You authenticate with a pk_live_…
or pk_test_…
bearer key. You create a job against either a tool (edit an image you supply) or a model (generate from a prompt). The create call returns immediately with a job id
. You poll GET /v1/jobs/{id}
until succeeded
or failed
. Credits are reserved when the job starts and settled when it finishes. There is no CORS on the API on purpose. Keys stay on your server.
Authorization: Bearer pk_live_YOUR_KEY
Rules that matter in production:
403 plan_upgrade_required
).Check your balance and rate limit standing:
curl -s https://api.picverce.com/v1/me \
-H "Authorization: Bearer pk_live_YOUR_KEY"
Example shape:
{
"object": "account",
"credits": {
"available": 42,
"daily": 0,
"subscription": 323,
"purchased": 55,
"reserved_open": 0,
"plan": "Basic"
},
"rate_limit": {
"limit": 60,
"remaining": 58,
"reset_at": "2026-08-26T12:15:00.000Z"
}
}
Liveness (no key):
curl -s https://api.picverce.com/health
Two catalogs, two job shapes.
| Kind | Endpoint to list | Job target | Input |
|---|---|---|---|
| Tool | |||
GET /v1/tools |
|||
tool id |
|||
Usually image_url plus options |
|||
| Model | |||
GET /v1/models |
|||
model id |
|||
prompt plus resolution / ratio / etc. |
curl -s https://api.picverce.com/v1/tools \
-H "Authorization: Bearer pk_live_YOUR_KEY"
curl -s https://api.picverce.com/v1/models \
-H "Authorization: Bearer pk_live_YOUR_KEY"
Public ids are stable Picverce AI names. Upstream provider slugs are never returned, so we can move a model without breaking your integration.
These map to Picverce AI product tools. Credit numbers match the website (TOOL_CREDIT_COSTS
).
| API id | Product name | Typical credits |
|---|---|---|
enhance |
||
| Image Enhancer | 2 | |
enhance_pro |
||
| Image Enhancer PRO | 6 | |
upscale |
||
| Image Upscaler | 2 / 3 / 6 by scale | |
sharpen |
||
| Image Sharpener | (see catalog) | |
text_clarity |
||
| Text Enhancer | (see catalog) | |
restore |
||
| Photo Restore | (see catalog) | |
face_restore |
||
| Face Restore | (see catalog) | |
anime_enhance |
||
| Anime Enhancer | (see catalog) | |
colorize |
||
| Image Colorizer | (see catalog) | |
photo_to_anime |
||
| Photo to Anime | (see catalog) | |
photo_to_cartoon |
||
| Photo to Cartoon | (see catalog) | |
photo_to_sketch |
||
| Photo to Sketch | (see catalog) | |
background_remover |
||
| Background Remover | 2 | |
object_remover |
||
| Object Remover | (see catalog) | |
watermark_remover |
||
| Watermark Remover | (see catalog) | |
hairstyle |
||
| Hairstyle Changer | (see catalog) | |
outfit |
||
| Outfit Generator | (see catalog) |
Always trust GET /v1/tools
/ GET /v1/tools/{id}
for the live input_schema
and credit object.
v1 catalogs more tools than the worker will execute yet. Runnable job tools right now:
background_remover
(Background Remover)enhance
(Image Enhancer)upscale
(Image Upscaler)Other tool ids return a clear “in catalog but not yet runnable” style error until we expand the allow-list. Generation models are available through the Models API path as documented in OpenAPI.
GET /v1/models
lists 26 generation models with display names, credit bands by resolution, ratios, reference-image rules, and variation caps.
Examples of public ids and Picverce AI display names:
| API id | Display name |
|---|---|
nano-banana-2 |
|
| Nano Banana 2 | |
nano-banana-pro |
|
| Nano Banana Pro | |
gpt-image-2 |
|
| GPT Image 2 | |
chatgpt-1-5 |
|
| Chatgpt 1.5 | |
seedream-3 |
|
| Seedream 3 | |
seedream-4 |
|
| Seedream 4 | |
seedream-4-5 |
|
| Seedream 4.5 | |
seedream-5-lite |
|
| Seedream 5 Lite | |
qwen-image-2-pro |
|
| Qwen Image 2 Pro | |
qwen-image-2 |
|
| Qwen Image 2 | |
flux-2-pro |
|
| Flux 2 Pro | |
flux-2-max |
|
| Flux 2 Max | |
flux-2-flex |
|
| Flux 2 Flex | |
flux-1-1-pro |
|
| Flux 1.1 Pro | |
flux-schnell |
|
| Flux Schnell | |
imagen-4 |
|
| Imagen 4 | |
imagen-4-ultra |
|
| Imagen 4 Ultra | |
ideogram-3 |
|
| Ideogram 3 | |
ideogram-3-turbo |
|
| Ideogram 3 Turbo | |
recraft-v3 |
|
| Recraft V3 | |
sd-3-5-large |
|
| SD 3.5 Large | |
sd-3-5-turbo |
|
| SD 3.5 Turbo | |
grok-imagine |
|
| xAI Grok Imagine |
(Plus the remaining Qwen / Seedream entries in the live catalog.)
Credits are variable by resolution. Read them from the catalog, do not hardcode forever.
Example: Background Remover on a public image URL.
curl -s -X POST https://api.picverce.com/v1/jobs \
-H "Authorization: Bearer pk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: demo-bg-001" \
-d '{
"tool": "background_remover",
"input": {
"image_url": "https://example.com/product.jpg"
}
}'
You get a job object back right away (queued
or similar). Poll:
curl -s https://api.picverce.com/v1/jobs/JOB_ID \
-H "Authorization: Bearer pk_live_YOUR_KEY"
When status
is succeeded
, the result includes an output image URL. Download it from your server.
curl -s -X POST https://api.picverce.com/v1/jobs \
-H "Authorization: Bearer pk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: demo-upscale-4x-001" \
-d '{
"tool": "upscale",
"input": {
"image_url": "https://example.com/hero.jpg",
"scale": 4
}
}'
Credits for upscale depend on 2
, 4
, or 8
(see catalog: typically 2 / 3 / 6).
curl -s -X POST https://api.picverce.com/v1/jobs \
-H "Authorization: Bearer pk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"tool": "enhance",
"input": {
"image_url": "https://example.com/soft-phone.jpg",
"face_enhance": false
}
}'
Shape is the same endpoint, different target field:
curl -s -X POST https://api.picverce.com/v1/jobs \
-H "Authorization: Bearer pk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: demo-flux-schnell-001" \
-d '{
"model": "flux-schnell",
"input": {
"prompt": "16:9 product photo of a ceramic mug on a wooden table, soft daylight, no text",
"resolution": "1K",
"aspect_ratio": "16:9"
}
}'
Exact input
fields depend on the model. Always read GET /v1/models/{id}
before you ship.
const API = 'https://api.picverce.com';
const KEY = process.env.PICVERCE_API_KEY;
async function createBackgroundJob(imageUrl) {
const res = await fetch(`${API}/v1/jobs`, {
method: 'POST',
headers: {
Authorization: `Bearer ${KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': `bg-${Date.now()}`,
},
body: JSON.stringify({
tool: 'background_remover',
input: { image_url: imageUrl },
}),
});
if (!res.ok) throw new Error(await res.text());
return res.json();
}
async function waitForJob(id, { intervalMs = 2000, timeoutMs = 120000 } = {}) {
const start = Date.now();
for (;;) {
const res = await fetch(`${API}/v1/jobs/${id}`, {
headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) throw new Error(await res.text());
const job = await res.json();
if (job.status === 'succeeded' || job.status === 'failed' || job.status === 'canceled') {
return job;
}
if (Date.now() - start > timeoutMs) throw new Error('job timeout');
await new Promise((r) => setTimeout(r, intervalMs));
}
}
const created = await createBackgroundJob('https://example.com/shoe.png');
const done = await waitForJob(created.id);
console.log(done.status, done.output);
| HTTP | Code | Meaning |
|---|---|---|
| 401 | invalid_api_key |
|
| Missing, malformed, unknown, or revoked | ||
| 402 | insufficient_credits |
|
| Valid key, not enough balance | ||
| 403 | plan_upgrade_required |
|
| No subscription and no credit pack | ||
| 404 | ||
invalid_tool / invalid_model / job_not_found |
||
| Bad id or not yours | ||
| 422 | validation_error |
|
| Body understood and refused | ||
| 429 | rate_limited |
|
| Too many requests this minute | ||
| 500 | internal_error |
|
| Our side |
Responses include a request id. Rate limit headers (X-RateLimit-*
) ride on authenticated calls.
API jobs spend the same credits as Picverce AI in the browser.
reserved_open
until they settle.Manage keys and review usage charts under Account → API Keys on Picverce AI.
Send Idempotency-Key
on POST /v1/jobs
when your client may retry. Replays with the same key return the same job instead of double-charging. Use a new key for a new piece of work.
GET /v1/tools
/ GET /v1/models
The OpenAPI file at picverce.com/openapi-v1.yaml is the contract. If this article and the YAML disagree, trust the YAML.
GET /v1/me
GET /v1/tools
and GET /v1/models
POST /v1/jobs
with background_remover
, enhance
, or upscale
GET /v1/jobs/{id}
until doneIf you build something on the Picverce AI Public API, tell us what you shipped. We are expanding the runnable Tools allow-list next.
— Picverce AI