Retrieve a generated image

March 9, 2026 (November 2, 2026)

Table of contents

  1. Request Headers
  2. Path parameter
  3. Responses
  4. Image Status Values
  5. Model
  6. Generation mode
  7. Examples
  8. Try It

Use this endpoint to retrieve a generated image. Attempting to retrieve an image that is still processing will return the current status. Poll until image_status_final is true.

To create images, use POST images/create.

https://api.useapi.net/v2/pixverse/images/image_id

Request Headers 
Authorization: Bearer {API token}
Content-Type: application/json
Path parameter
  • image_id is required. Specify the image_id you want to retrieve (from success_ids array returned by POST images/create).
Responses

  • 200 OK

    {
    "image_id": "user:<userid>-pixverse:<email>-image:<number>",
    "image_status": 1,
    "account_id": 12345678,
    "model": "seedream-4.0",
    "prompt": "<prompt>",
    "quality": "1080p",
    "aspect_ratio": "auto",
    "seed": 12345,
    "image_url": "https://media.pixverse.ai/...webp",
    "output_width": 1920,
    "output_height": 1080,
    "customer_img_paths": [],
    "customer_img_urls": null,
    "cost_credits": 0,
    "relax_mode": true,
    "generation_mode": {
        "version": 1,
        "requested_relax_mode": true,
        "resolved_mode": "relax",
        "billing_type": "free",
        "actual_cost": 0
    },
    "queue_data": {
        "estimated_gen_time": 60,
        "processing_start_time": "2026-03-08T00:30:00Z",
        "queue_count": 0,
        "queue_time": 1
    },
    "created_at": "2026-03-08T00:30:00Z",
    "updated_at": "2026-03-08T00:31:00Z",
    "image_status_name": "COMPLETED",
    "image_status_final": true
}

  • 400 Bad Request

    {
    "error": "<Error message>",
    "code": 400
}

  • 401 Unauthorized

    {
  "error": "Unauthorized",
  "code": 401
}

  • 404 Not Found

    The image was deleted or not found.

    {
    "error": "The original image has been deleted"
}
Image Status Values
image_status image_status_name image_status_final Description
1 COMPLETED true Image ready, check image_url
5 QUEUED false Waiting in queue
7 MODERATED true Content moderation triggered
8 FAILED true PixVerse failed to make the image, no reason given. Retry
9 GENERATING false Image is being generated
10 PROCESSING false Post-processing
17 MODERATED true Policy violation detected after the image was made
Model 
{   // TypeScript, all fields are optional
    image_id: string
    image_status: number
    account_id: number
    asset_id: number
    asset_source: number
    asset_type: number
    create_mode: string
    creation_type: number
    model: string
    prompt: string
    quality: string
    aspect_ratio: string
    seed: number
    image_path: string
    image_url: string
    output_width: number
    output_height: number
    customer_img_paths: string[]
    customer_img_urls: string[] | null
    platform: string
    cost_credits: number
    relax_mode: boolean | null
    generation_mode?: {
        version: number
        requested_relax_mode: boolean
        resolved_mode: string       // relax | regular
        billing_type: string        // free | full_price
        actual_cost: number
    } | null
    queue_data?: {
        estimated_gen_time: number
        processing_start_time: string
        queue_count: number
        queue_time: number
        reason?: string
        slow_queue?: boolean
        platform?: string
        task_id?: number
    }
    created_at: string
    updated_at: string
    is_collected: boolean
    water_mark: boolean
    media_locked: number
    // added
    image_status_name: string
    image_status_final: boolean
    error: string
}

queue_data is present while a generation is waiting and reports its position — queue_count is the number of tasks ahead, queue_time the wait so far, and estimated_gen_time the projected generation time in seconds. It comes straight from PixVerse and is passed through unchanged.

When slow_queue is true the account has been moved to a reduced-priority queue and reason says why. The value daily_limit_exceeded means the account has passed its daily allowance for that particular unlimited Relax Mode model — the request is not rejected and still costs no credits, it just takes considerably longer. The allowance is per model, so the same account keeps running at full speed on every other model. Switch model, or spread the load across more accounts, if you see this persistently.

Generation mode

cost_credits is what PixVerse charged for the image, 0 for an image made in Relax Mode.

generation_mode shows how PixVerse handled the relax_mode parameter of POST images/create:

  • requested_relax_mode is the relax_mode value you sent.
  • resolved_mode is the mode PixVerse used: relax (free Relax Mode) or regular (paid, full speed).
  • billing_type is free or full_price, and actual_cost is the credits charged.

When relax_mode was left out, both relax_mode and generation_mode are null, and cost_credits tells you whether the image was free. In that case PixVerse uses Relax Mode whenever the account’s plan makes the model free.

Examples 
  • curl "https://api.useapi.net/v2/pixverse/images/image_id" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …"

  • const token = "API token";
const image_id = "image_id to retrieve";
const apiUrl = `https://api.useapi.net/v2/pixverse/images/${image_id}`;
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});

  • import requests
token = "API token"
image_id = "image_id to retrieve"
apiUrl = f"https://api.useapi.net/v2/pixverse/images/{image_id}"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
Try It