API docs - VividForge AI

Introduction

The API speaks JSON over HTTPS. Every request is authenticated with an API key and every response is JSON, including errors. All endpoints live under this base URL:

Base URL

https://your-site.com/api/v1

Four images per call

Each request returns a batch of four variations.

Server-side keys

Keys stay on your server, never in a browser.

Shared credits

Calls draw from your plan balance.

Authentication

Create a key in API Keys in your dashboard and send it as a bearer token. Keys are shown once, so store them in an environment variable. Revoking a key stops it immediately.

Header

Authorization: Bearer vf_live_••••••••••••••••

Create a generation

POSThttps://your-site.com/api/v1/generations

Renders four variations and saves them to the account that owns the key, where they also appear in My Generations.

Request body parameters
Parameter	Type	Description
promptrequired	string	What to create, 3 to 1,000 characters.
negative_prompt	string	Things to keep out of the image, up to 500 characters.
style	string	photorealistic, anime, cyberpunk, 3d-render, oil-painting or digital-art. Defaults to cyberpunk.
aspect_ratio	string	1:1, 16:9, 9:16 or 4:3. Defaults to 1:1.
quality	string	standard (1024 px), hd (2048 px) or 4k (3840 px). Defaults to hd.
seed	integer	0 to 2147483647. Omit for a random seed. The same seed and settings return the same images.
guidance_scale	number	1 to 20 in steps of 0.5. Higher follows the prompt more literally. Defaults to 7.5.

curl -X POST https://your-site.com/api/v1/generations \
  -H "Authorization: Bearer $VIVIDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a neon koi pond at midnight, mist over the water",
    "style": "cyberpunk",
    "aspect_ratio": "16:9",
    "quality": "hd",
    "guidance_scale": 7.5
  }'

A successful call returns 201 Created with the batch:

Response

{
  "id": "6f1c2a9e-4b7d-4c1e-9a3f-2d8e5b7c1a90",
  "object": "generation.batch",
  "created": 1761379200,
  "model": "forge-v3",
  "prompt": "a neon koi pond at midnight, mist over the water",
  "negative_prompt": "",
  "style": "cyberpunk",
  "aspect_ratio": "16:9",
  "quality": "hd",
  "guidance_scale": 7.5,
  "sampler": "DPM++ SDE Karras",
  "steps": 36,
  "images": [
    {
      "id": "0b9d6e1f-3c2a-4f8e-b5d7-9a1c2e3f4b5d",
      "url": "https://your-site.com/images/forge/cyber-city-4.png",
      "width": 2048,
      "height": 1152,
      "seed": 1048576,
      "upscaled": false,
      "background_removed": false
    }
  ],
  "credits_used": 8,
  "credits_remaining": 492
}

List generations

GEThttps://your-site.com/api/v1/generations?limit=10

Returns your most recent images, newest first. limit accepts 1 to 50 and defaults to 10.

cURL

curl https://your-site.com/api/v1/generations?limit=10 \
  -H "Authorization: Bearer $VIVIDFORGE_API_KEY"

Account and credits

GEThttps://your-site.com/api/v1/account

Check your plan and remaining credits before a large batch job.

cURL

curl https://your-site.com/api/v1/account \
  -H "Authorization: Bearer $VIVIDFORGE_API_KEY"

Response

{
  "object": "account",
  "plan": "pro",
  "credits": { "limit": 500, "used": 160, "remaining": 340 },
  "cycle_started_at": "2026-10-01T09:12:44.000Z",
  "cycle_ends_at": "2026-10-31T09:12:44.000Z"
}

Credit costs

Calls cost exactly what the studio charges for the same settings.

Credit cost per image by quality and plan
Quality	Free plan	Pro and Enterprise
Standard	1 credit per image	Unlimited
HD	2 credits per image	2 fast credits per image
4K	4 credits per image	4 fast credits per image

Errors

Errors share one shape, with a stable type you can branch on and a human-readable message.

Error response

{
  "error": {
    "type": "insufficient_credits",
    "message": "This batch needs 16 credits and your balance is too low. Top up or switch to Standard quality."
  }
}

Error codes
Status	Type	Meaning
401	authentication_error	The API key is missing, mistyped or revoked.
402	insufficient_credits	The request costs more credits than your balance holds.
405	invalid_request_error	The HTTP method is not supported on this endpoint.
422	invalid_request_error	A parameter is missing or outside its allowed values. The message names it.
500	api_error	Something failed on our side. Retry with backoff.