# Introducing the Picverce AI Public API for image tools and generation models

> Source: <https://dev.to/daniyal_khan_fd094511e963/introducing-the-picverce-ai-public-api-for-image-tools-and-generation-models-33eh>
> Published: 2026-08-27 07:01:34+00:00

**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](https://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.

``` js
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](https://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**