> ## 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 image

> Generate an image from a text prompt, or edit/upscale an existing image. Returns a job that you poll or stream for completion.

This endpoint also handles **image editing** (provide a source image via `files`) and **image upscaling** (provide an image with an upscale model).




## OpenAPI

````yaml /openapi.yaml post /image
openapi: 3.1.0
info:
  title: Varg Gateway API
  version: 0.1.0
  description: >-
    Unified REST API for AI generation (video, image, speech, music) at
    api.varg.ai
servers:
  - url: https://api.varg.ai/v1
security:
  - bearerAuth: []
tags:
  - name: Generation
    description: Create AI-generated content
  - name: Jobs
    description: Manage and monitor generation jobs
  - name: Files
    description: Upload files for use in generation
  - name: Reference
    description: Available models and voices
  - name: Media Processing
    description: FFmpeg-powered video utilities (trim, resize, probe, custom commands)
  - name: Account
    description: Account info, balance, and usage
paths:
  /image:
    post:
      tags:
        - Generation
      summary: Generate image
      description: >
        Generate an image from a text prompt, or edit/upscale an existing image.
        Returns a job that you poll or stream for completion.


        This endpoint also handles **image editing** (provide a source image via
        `files`) and **image upscaling** (provide an image with an upscale
        model).
      operationId: createImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - prompt
              properties:
                model:
                  type: string
                  description: >
                    Image model to use. Also accepts image editing and upscale
                    models.


                    **Text-to-image:** `flux-pro`, `flux-dev`, `flux-schnell`,
                    `nano-banana-pro`, `recraft-v3`, `phota`,
                    `grok-imagine-image`, `soul`


                    **Image editing:** `nano-banana-pro/edit`,
                    `nano-banana-2/edit`, `phota/edit`, `phota/enhance`,
                    `grok-imagine-image/edit`, `seedream-v4.5/edit`,
                    `qwen-angles`


                    **Image upscale:** `seedvr`, `recraft-clarity`,
                    `clarity-upscaler`, `topaz`, `ccsr`, `aura-sr`
                  examples:
                    - flux-pro
                    - flux-schnell
                    - nano-banana-pro
                    - recraft-v3
                    - phota
                    - grok-imagine-image
                    - soul
                    - nano-banana-pro/edit
                    - seedvr
                    - topaz
                prompt:
                  type: string
                  description: >-
                    Text description of the image to generate. For editing
                    models, describe the desired change. For upscale models, can
                    be empty.
                  example: sunset over mountains, dramatic lighting, photorealistic
                aspect_ratio:
                  type: string
                  description: Output aspect ratio
                  default: '1:1'
                  examples:
                    - '1:1'
                    - '16:9'
                    - '9:16'
                    - '4:3'
                    - '3:4'
                files:
                  type: array
                  description: |
                    Input images for editing, style transfer, or upscaling.

                    - **Image editing:** 1 source image URL
                    - **Image upscale:** 1 image URL
                    - **Multi-angle (qwen-angles):** 1 source image
                  items:
                    type: object
                    required:
                      - url
                    properties:
                      url:
                        type: string
                        format: uri
                        description: URL of the input image
                provider_options:
                  type: object
                  description: Additional options passed directly to the provider
                  additionalProperties: true
            examples:
              flux-pro:
                summary: Flux Pro — text-to-image
                value:
                  model: flux-pro
                  prompt: >-
                    a minimalist logo design, geometric shapes, blue and white
                    gradient
                  aspect_ratio: '1:1'
              flux-schnell:
                summary: Flux Schnell — fast text-to-image
                value:
                  model: flux-schnell
                  prompt: sunset over mountains, dramatic lighting, photorealistic
                  aspect_ratio: '16:9'
              nano-banana-pro:
                summary: Nano Banana Pro — photorealistic
                value:
                  model: nano-banana-pro
                  prompt: >-
                    professional headshot of a woman in a modern office, natural
                    lighting, shallow depth of field
                  aspect_ratio: '1:1'
              nano-banana-edit:
                summary: Nano Banana Pro — image editing
                value:
                  model: nano-banana-pro/edit
                  prompt: change the shirt color to bright red
                  files:
                    - url: https://example.com/portrait.jpg
              recraft-v3:
                summary: Recraft V3 — design and illustration
                value:
                  model: recraft-v3
                  prompt: >-
                    flat vector illustration of a coffee shop storefront, warm
                    colors, clean lines
                  aspect_ratio: '1:1'
              phota:
                summary: Phota — text-to-image
                value:
                  model: phota
                  prompt: >-
                    product photo of a ceramic mug on a wooden table, morning
                    light, steam rising
                  aspect_ratio: '4:3'
              phota-edit:
                summary: Phota Edit — image editing
                value:
                  model: phota/edit
                  prompt: remove the background and replace with a clean white studio
                  files:
                    - url: https://example.com/product.jpg
              grok-imagine-image:
                summary: Grok Imagine — text-to-image
                value:
                  model: grok-imagine-image
                  prompt: >-
                    a medieval castle perched on a cliff overlooking a stormy
                    sea
                  aspect_ratio: '16:9'
              qwen-angles:
                summary: Qwen Angles — multi-angle views
                value:
                  model: qwen-angles
                  prompt: generate multiple angles of this product
                  files:
                    - url: https://example.com/product.jpg
              soul:
                summary: Soul — text-to-image (Higgsfield)
                value:
                  model: soul
                  prompt: >-
                    a cyberpunk street scene at night, neon reflections on wet
                    pavement
                  aspect_ratio: '16:9'
              upscale-seedvr:
                summary: SeedVR — image upscale
                value:
                  model: seedvr
                  prompt: ''
                  files:
                    - url: https://example.com/low-res-photo.jpg
              upscale-topaz:
                summary: Topaz — image upscale
                value:
                  model: topaz
                  prompt: ''
                  files:
                    - url: https://example.com/low-res-photo.jpg
      responses:
        '202':
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthError'
        '402':
          $ref: '#/components/responses/InsufficientBalanceError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/ProviderError'
components:
  schemas:
    JobResponse:
      type: object
      required:
        - job_id
        - status
        - model
        - created_at
      properties:
        job_id:
          type: string
          description: Unique job identifier
          example: job_a1b2c3d4
        status:
          type: string
          enum:
            - queued
            - processing
            - completed
            - failed
            - cancelled
          description: Current job status
          example: completed
        model:
          type: string
          description: Resolved model identifier (provider:model format)
          example: fal:kling-v2.5
        created_at:
          type: string
          format: date-time
          description: When the job was created
          example: '2026-02-13T10:00:00Z'
        completed_at:
          type: string
          format: date-time
          description: When the job finished (completed, failed, or cancelled)
          example: '2026-02-13T10:02:30Z'
        output:
          type: object
          description: Job output, present when status is completed
          properties:
            url:
              type: string
              format: uri
              description: URL of the generated file on s3.varg.ai
              example: https://s3.varg.ai/o/job_a1b2c3d4.mp4
            media_type:
              type: string
              description: MIME type of the output
              example: video/mp4
        cache:
          type: object
          description: Cache metadata
          properties:
            hit:
              type: boolean
              description: Whether this result was served from cache
              example: false
            key:
              type: string
              description: Cache key for this request
              example: sha256:abc123...
        error:
          type: string
          description: Error message, present when status is failed
          example: Provider returned an error
    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
          example: ValidationError
        message:
          type: string
          description: Human-readable error description
          example: prompt is required
        field:
          type: string
          description: The field that caused the error, if applicable
          example: prompt
        provider:
          type: string
          description: The upstream provider that returned the error, if applicable
          example: fal
        statusCode:
          type: number
          description: HTTP status code
          example: 400
  responses:
    ValidationError:
      description: Invalid request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: ValidationError
            message: prompt is required
            field: prompt
            statusCode: 400
    AuthError:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: AuthError
            message: Invalid API key
            statusCode: 401
    InsufficientBalanceError:
      description: Account balance too low
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: InsufficientBalanceError
            message: Insufficient balance. Add credits at varg.ai/dashboard.
            statusCode: 402
    RateLimitError:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: RateLimitError
            message: Rate limit exceeded. Retry after 60 seconds.
            statusCode: 429
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: InternalError
            message: An unexpected error occurred
            statusCode: 500
    ProviderError:
      description: Upstream provider returned an error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: ProviderError
            message: Provider returned an error
            provider: fal
            statusCode: 502
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: varg_xxx
      description: |
        API key from [varg.ai/dashboard](https://varg.ai/dashboard).

        Pass as `Authorization: Bearer varg_xxx`.

````