Generate an image

curl --request POST \
  --url https://api.varg.ai/v2/image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "flux_schnell",
  "prompt": "a cat astronaut floating in space, photorealistic",
  "aspect_ratio": "16:9"
}
'

{
  "id": "job_a1b2c3d4e5f6",
  "tool": "image",
  "input": {},
  "output": {
    "version": "<string>",
    "outputs": [
      {
        "url": "<string>",
        "file_id": "<string>",
        "media_type": "video/mp4",
        "size_bytes": 123,
        "thumbnail_url": "<string>"
      }
    ]
  },
  "error": {},
  "progress_message": "stitching 3/8 (40%)",
  "progress": 123,
  "progress_metadata": {},
  "estimated_duration_ms": 123,
  "estimated_cost_cents": 123,
  "actual_cost_cents": 123,
  "pricing": {
    "estimated": 123,
    "actual": 123,
    "billing": "<string>",
    "cached": true,
    "billed_units": {
      "images": 1
    },
    "pricing_id": "<string>"
  },
  "provider": "fal",
  "provider_model": "fal:flux_schnell",
  "provider_status": "<string>",
  "provider_job_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "urls": {
    "self": "<string>",
    "status": "<string>",
    "refresh": "<string>",
    "cancel": "<string>",
    "retry": "<string>"
  }
}

{
  "id": "job_a1b2c3d4e5f6",
  "status": "queued",
  "tool": "image",
  "input": {
    "model": "flux_schnell",
    "prompt": "a cat astronaut"
  },
  "output": null,
  "error": null,
  "estimated_cost_cents": 4,
  "actual_cost_cents": null,
  "pricing": {
    "estimated": 4,
    "actual": null,
    "billing": "metered",
    "cached": null,
    "billed_units": null,
    "pricing_id": "ppr_abc123"
  },
  "provider": "fal",
  "provider_model": "fal:flux_schnell",
  "created_at": "2026-07-01T10:00:00Z",
  "urls": {
    "self": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6",
    "status": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/status",
    "refresh": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/refresh",
    "cancel": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/cancel",
    "retry": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/retry"
  }
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance to run this job"
  }
}

{
  "error": {
    "code": "model_not_found",
    "message": "Unknown model: flux-shnell"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Body validation failed (text: Required)"
  }
}

{
  "error": {
    "code": "model_not_found",
    "message": "Unknown model: flux-shnell",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "model_not_found",
    "message": "Unknown model: flux-shnell",
    "details": "<unknown>"
  }
}

POST

image

curl --request POST \
  --url https://api.varg.ai/v2/image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "flux_schnell",
  "prompt": "a cat astronaut floating in space, photorealistic",
  "aspect_ratio": "16:9"
}
'

{
  "id": "job_a1b2c3d4e5f6",
  "tool": "image",
  "input": {},
  "output": {
    "version": "<string>",
    "outputs": [
      {
        "url": "<string>",
        "file_id": "<string>",
        "media_type": "video/mp4",
        "size_bytes": 123,
        "thumbnail_url": "<string>"
      }
    ]
  },
  "error": {},
  "progress_message": "stitching 3/8 (40%)",
  "progress": 123,
  "progress_metadata": {},
  "estimated_duration_ms": 123,
  "estimated_cost_cents": 123,
  "actual_cost_cents": 123,
  "pricing": {
    "estimated": 123,
    "actual": 123,
    "billing": "<string>",
    "cached": true,
    "billed_units": {
      "images": 1
    },
    "pricing_id": "<string>"
  },
  "provider": "fal",
  "provider_model": "fal:flux_schnell",
  "provider_status": "<string>",
  "provider_job_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "urls": {
    "self": "<string>",
    "status": "<string>",
    "refresh": "<string>",
    "cancel": "<string>",
    "retry": "<string>"
  }
}

{
  "id": "job_a1b2c3d4e5f6",
  "status": "queued",
  "tool": "image",
  "input": {
    "model": "flux_schnell",
    "prompt": "a cat astronaut"
  },
  "output": null,
  "error": null,
  "estimated_cost_cents": 4,
  "actual_cost_cents": null,
  "pricing": {
    "estimated": 4,
    "actual": null,
    "billing": "metered",
    "cached": null,
    "billed_units": null,
    "pricing_id": "ppr_abc123"
  },
  "provider": "fal",
  "provider_model": "fal:flux_schnell",
  "created_at": "2026-07-01T10:00:00Z",
  "urls": {
    "self": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6",
    "status": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/status",
    "refresh": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/refresh",
    "cancel": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/cancel",
    "retry": "https://api.varg.ai/v2/jobs/job_a1b2c3d4e5f6/retry"
  }
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance to run this job"
  }
}

{
  "error": {
    "code": "model_not_found",
    "message": "Unknown model: flux-shnell"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Body validation failed (text: Required)"
  }
}

{
  "error": {
    "code": "model_not_found",
    "message": "Unknown model: flux-shnell",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "model_not_found",
    "message": "Unknown model: flux-shnell",
    "details": "<unknown>"
  }
}

Authorizations

Authorization

string

header

required

varg API key (varg_...). Get one at app.varg.ai or run bunx vargai login. App sessions may alternatively send a Supabase JWT.

Headers

Idempotency-Key

string

Any unique string. Retrying a request with the same key returns the existing job (HTTP 200) instead of creating and charging a new one (HTTP 202).

Body

application/json

model

string

required

Model id (flux_schnell) or provider-pinned (fal:flux_schnell)

Example:

"flux_schnell"

prompt

string

Maximum string length: 2000

aspect_ratio

string

Example:

"16:9"

files

object[]

Source images for editing / reference

Maximum array length: 10

Show child attributes

provider_options

object

Provider-native overrides, keyed by provider id (e.g. a fal object with seed, num_images, ...). Discover per-model fields via GET /tools/{tool_key}?model=<model>.

Show child attributes

options

object

Cross-cutting job options

Show child attributes

Response

Idempotency replay — the existing job for this Idempotency-Key (no new charge).

string

Example:

"job_a1b2c3d4e5f6"

status

enum<string>

Lifecycle is queued then submitting then running, ending in a terminal status (completed, failed, or cancelled).

Available options:

queued,

submitting,

running,

completed,

failed,

cancelled

tool

string

Example:

"image"

input

object

The request body as submitted (model, prompt, ...)

output

object | null

Canonical output envelope. Present only when the job is completed.

Show child attributes

error

object | null

progress_message

string | null

Example:

"stitching 3/8 (40%)"

progress

number | null

Fraction 0..1

progress_metadata

object | null

estimated_duration_ms

integer | null

estimated_cost_cents

integer | null

actual_cost_cents

integer | null

pricing

object

Structured pricing. 1 credit = 1 cent = $0.01.

Show child attributes

provider

string | null

Example:

"fal"

provider_model

string | null

Example:

"fal:flux_schnell"

provider_status

string | null

The provider's raw status string

provider_job_id

string | null

created_at

string<date-time>

started_at

string<date-time> | null

completed_at

string<date-time> | null

urls

object

Lifecycle URLs (present on creation responses)

Show child attributes

Render API Generate a video

Overview

Generation

Tools

Jobs

Files

Pricing & Billing

Account

Generate an image

Authorizations

Headers

Body

Response