DEV Community

Cover image for Introducing the Picverce AI Public API for image tools and generation models
Daniyal khan
Daniyal khan

Posted on AI-assisted

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

#ai #api #backend #tools

Introducing the Picverce AI Public API

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
Enter fullscreen mode Exit fullscreen mode

OpenAPI contract:

https://picverce.com/openapi-v1.yaml
Enter fullscreen mode Exit fullscreen mode

Human docs:

https://picverce.com/api-docs/
Enter fullscreen mode Exit fullscreen mode

Create keys in Account → API Keys:

https://picverce.com/account/?tab=api
Enter fullscreen mode Exit fullscreen mode

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.

Why we built it

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:

  • Server-side keys (no key in browser JavaScript)
  • Async jobs so a slow model never becomes your timeout
  • One credit balance shared with the website
  • Discoverable catalogs for tools and models

Public API v1.0.0 is that surface.

Design in one paragraph

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.

Auth 

Authorization: Bearer pk_live_YOUR_KEY
Enter fullscreen mode Exit fullscreen mode

Rules that matter in production:

  1. Server-side only. The gateway does not send CORS headers. A key in frontend JS will not work from a browser page.
  2. Treat a key like a password. Rotate and revoke from Account → API Keys.
  3. You can hold up to 10 active keys. Revoked keys stay in history so old job rows still make sense.
  4. Access requires an active Basic / Standard / Premium plan or a purchased credit pack. Free alone cannot create keys or call authenticated routes (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"
Enter fullscreen mode Exit fullscreen mode

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"
  }
}
Enter fullscreen mode Exit fullscreen mode

Liveness (no key):

curl -s https://api.picverce.com/health
Enter fullscreen mode Exit fullscreen mode

Tools vs Models

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"
Enter fullscreen mode Exit fullscreen mode

Public ids are stable Picverce AI names. Upstream provider slugs are never returned, so we can move a model without breaking your integration.

Tools catalog (product names)

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.

What is runnable today

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.

Models catalog (generation)

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.

Creating a Tools job

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

When status is succeeded, the result includes an output image URL. Download it from your server.

Upscale with a scale option 

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
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Credits for upscale depend on 2, 4, or 8 (see catalog: typically 2 / 3 / 6).

Enhance 

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
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Creating a Models job

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Exact input fields depend on the model. Always read GET /v1/models/{id} before you ship.

Node example (poll loop) 

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);
Enter fullscreen mode Exit fullscreen mode

Errors you will actually see

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.

Credits and billing (same wallet as the site)

API jobs spend the same credits as Picverce AI in the browser.

  • Free daily credits alone do not unlock the API.
  • Active Basic, Standard, or Premium unlocks API access.
  • Buying a credit pack also unlocks API access, even on Free.
  • Open jobs hold credits in reserved_open until they settle.

Manage keys and review usage charts under Account → API Keys on Picverce AI.

Idempotency

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.

What we are not shipping in this post

  • Browser-side keys (by design)
  • Claiming every catalog tool is runnable today (only Background Remover, Image Enhancer, and Image Upscaler are in the live allow-list)
  • Inventing credit numbers that disagree with 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.

Quick start checklist

  1. Create a Picverce AI account at picverce.com
  2. Subscribe or buy a credit pack
  3. Open Account → API Keys and create a live key
  4. Call GET /v1/me
  5. Call GET /v1/tools and GET /v1/models
  6. POST /v1/jobs with background_remover, enhance, or upscale
  7. Poll GET /v1/jobs/{id} until done
  8. Keep the key on your server

Links

If 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

Top comments (0)