> ## Documentation Index > Fetch the complete documentation index at: https://docs.varg.ai/llms.txt > Use this file to discover all available pages before exploring further. # Generate an image > Create an image generation job. Also handles image editing (send a source image in `files` with an edit-capable model like `nano_banana_pro/edit`) and image upscaling (`clarity_upscaler`, `aura_sr`, `topaz`, ...). Returns `202` with a queued job. Poll `GET /jobs/{id}` until `completed`. ## OpenAPI ````yaml /openapi.yaml post /image openapi: 3.1.0 info: title: varg API version: 2.0.0 description: | Unified REST API for AI media generation at `api.varg.ai/v2`. One API key, ~80 models across 8 providers, async jobs, stable output URLs on `s3.varg.ai`, files with lineage, and transparent credit billing (1 credit = 1 cent = $0.01). **The async job pattern:** every generation request returns `202 Accepted` with a job object (`status: queued`). Poll `GET /jobs/{id}` until the job reaches a terminal status (`completed`, `failed`, or `cancelled`), then read `output.outputs[0].url`. Alternatively, set `options.webhook_url` in the request to receive an HMAC-signed callback when the job finishes. servers: - url: https://api.varg.ai/v2 security: - bearerAuth: [] tags: - name: Generation description: >- Create generation jobs (image, video, speech, music, transcription, ffmpeg, render, pipeline) - name: Tools description: Discover tools, their schemas, and call any tool generically - name: Jobs description: Poll and manage job lifecycle - name: Files description: Upload, import, probe, and manage files - name: Lineage description: Resolve which job produced a file - name: Pricing description: Estimate costs and browse the price catalog - name: Billing description: Balance, usage, and transaction history - name: Account description: Identity and API key management paths: /image: post: tags: - Generation summary: Generate an image description: > Create an image generation job. Also handles image editing (send a source image in `files` with an edit-capable model like `nano_banana_pro/edit`) and image upscaling (`clarity_upscaler`, `aura_sr`, `topaz`, ...). Returns `202` with a queued job. Poll `GET /jobs/{id}` until `completed`. operationId: createImage parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImageRequest' examples: text-to-image: summary: Text to image value: model: flux_schnell prompt: a cat astronaut floating in space, photorealistic aspect_ratio: '16:9' image-edit: summary: Image editing (nano banana pro) value: model: nano_banana_pro/edit prompt: make the sky purple and add northern lights files: - url: https://s3.varg.ai/files/acc_x/file_abc.png pinned-provider: summary: Pin an exact provider value: model: fal:flux_schnell prompt: sunset over mountains provider-options: summary: Provider-native overrides value: model: flux_dev prompt: a serene mountain lake at sunrise provider_options: fal: seed: 42 num_images: 2 responses: '200': $ref: '#/components/responses/JobReplay' '202': $ref: '#/components/responses/JobAccepted' '402': $ref: '#/components/responses/InsufficientBalance' '404': $ref: '#/components/responses/ModelNotFound' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/NoPricing' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string description: | 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). schemas: ImageRequest: type: object required: - model properties: model: type: string description: Model id (`flux_schnell`) or provider-pinned (`fal:flux_schnell`) example: flux_schnell prompt: type: string maxLength: 2000 aspect_ratio: type: string example: '16:9' files: type: array maxItems: 10 items: $ref: '#/components/schemas/FileInput' description: Source images for editing / reference provider_options: $ref: '#/components/schemas/ProviderOptions' options: $ref: '#/components/schemas/JobOptions' FileInput: type: object required: - url properties: url: type: string format: uri description: >- Public http(s) URL — upload via POST /files first to get a stable varg URL ProviderOptions: type: object description: | 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=`. additionalProperties: type: object JobOptions: type: object description: Cross-cutting job options properties: webhook_url: type: string format: uri description: | HTTPS URL to receive the job snapshot when the job reaches a terminal status. Signed with an `X-Varg-Signature` HMAC header. 8 retries with exponential backoff. Job: type: object properties: id: type: string example: job_a1b2c3d4e5f6 status: $ref: '#/components/schemas/JobStatus' tool: type: string example: image input: type: object description: The request body as submitted (model, prompt, ...) output: oneOf: - $ref: '#/components/schemas/JobOutput' - type: 'null' error: type: - object - 'null' progress_message: type: - string - 'null' example: stitching 3/8 (40%) progress: type: - number - 'null' description: Fraction 0..1 progress_metadata: type: - object - 'null' estimated_duration_ms: type: - integer - 'null' estimated_cost_cents: type: - integer - 'null' actual_cost_cents: type: - integer - 'null' pricing: $ref: '#/components/schemas/JobPricing' provider: type: - string - 'null' example: fal provider_model: type: - string - 'null' example: fal:flux_schnell provider_status: type: - string - 'null' description: The provider's raw status string provider_job_id: type: - string - 'null' created_at: type: string format: date-time started_at: type: - string - 'null' format: date-time completed_at: type: - string - 'null' format: date-time urls: type: object description: Lifecycle URLs (present on creation responses) properties: self: type: string status: type: string refresh: type: string cancel: type: string retry: type: string ErrorResponse: type: object properties: error: type: object properties: code: type: string example: model_not_found message: type: string example: 'Unknown model: flux-shnell' details: {} JobStatus: type: string enum: - queued - submitting - running - completed - failed - cancelled description: | Lifecycle is `queued` then `submitting` then `running`, ending in a terminal status (`completed`, `failed`, or `cancelled`). JobOutput: type: object description: Canonical output envelope. Present only when the job is completed. properties: version: type: string const: v1 outputs: type: array items: type: object properties: url: type: string description: Stable varg-hosted URL (s3.varg.ai) file_id: type: string description: The file record for this output — use with /files and /lineage media_type: type: string example: video/mp4 size_bytes: type: integer thumbnail_url: type: - string - 'null' JobPricing: type: object description: Structured pricing. 1 credit = 1 cent = $0.01. properties: estimated: type: - integer - 'null' description: Reserved at creation (cents) actual: type: - integer - 'null' description: Charged at completion (cents). 0 for cache hits. billing: type: - string - 'null' cached: type: - boolean - 'null' description: true when the result came from cache (actual = 0) billed_units: type: - object - 'null' example: images: 1 pricing_id: type: - string - 'null' description: The pinned pricing rule this job was charged under responses: JobReplay: description: >- Idempotency replay — the existing job for this `Idempotency-Key` (no new charge). content: application/json: schema: $ref: '#/components/schemas/Job' JobAccepted: description: Job created and queued. Poll `urls.self` until terminal. headers: X-RateLimit-Limit: schema: type: string X-RateLimit-Remaining: schema: type: string X-RateLimit-Reset: schema: type: string content: application/json: schema: $ref: '#/components/schemas/Job' examples: queued: summary: Queued job value: 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 InsufficientBalance: description: Account balance too low to reserve the estimated cost content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficient: value: error: code: insufficient_balance message: Insufficient balance to run this job ModelNotFound: description: Unknown model or tool content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: model: value: error: code: model_not_found message: 'Unknown model: flux-shnell' ValidationError: description: Request body failed validation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid: value: error: code: invalid_request message: 'Body validation failed (text: Required)' RateLimited: description: Rate limit exceeded (sliding window per API key) headers: Retry-After: schema: type: string X-RateLimit-Limit: schema: type: string X-RateLimit-Remaining: schema: type: string X-RateLimit-Reset: schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NoPricing: description: No active pricing rule for this model content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer description: | varg API key (`varg_...`). Get one at [app.varg.ai](https://app.varg.ai) or run `bunx vargai login`. App sessions may alternatively send a Supabase JWT. ````