Create an image using a text prompt

Table of contents

March 9, 2026 (November 6, 2026)

  1. Model Comparison Matrix
  2. Aspect Ratios
  3. Unlimited Image Generation (Relax Mode)
  4. Request Headers
  5. Request Body
  6. Parameters
  7. Responses
  8. Model
  9. Examples
  10. Try It

Use pixverse.ai account to generate images. Supports text-to-image (t2i) and image-to-image (i2i) with reference images uploaded via POST files.

Model Comparison Matrix
Model Qualities Ref Images Est. Time
qwen-image (default) 720p, 1080p 1-3 via image_path_1…3 ~3s
nano-banana * 1080p 1-3 via image_path_1…3 ~10s
nano-banana-2 * 512p, 1080p, 1440p, 2160p 1-9 via image_path_1…9 ~30s
nano-banana-2.1 1080p, 1440p, 2160p 1-14 via image_path_1…14 ~15s
nano-banana-2-lite * 1080p 1-14 via image_path_1…14 ~7s
nano-banana-pro * 1080p, 1440p, 2160p 1-9 via image_path_1…9 ~60s
seedream-4.0 1080p, 1440p, 2160p 1-6 via image_path_1…6 ~10s
seedream-4.5 1440p, 2160p 1-6 via image_path_1…6 ~15s
seedream-5.0-pro 1080p, 1440p 1-10 via image_path_1…10 ~30s
seedream-5.0-lite 1440p, 1800p, 2160p 1-6 via image_path_1…6 ~30s
kling-3.0 1080p, 1440p 1 via image_path_1 ~15s
kling-o3 1080p, 1440p, 2160p 1 via image_path_1 ~20s
gpt-image-2.0 1080p, 1440p, 2160p 1-9 via image_path_1…9 ~30s
gpt-image-2.5-flare 1080p, 1440p, 2160p 1-16 via image_path_1…16 ~30s
gpt-image-2.5-sunburst 1080p, 1440p, 2160p 1-16 via image_path_1…16 ~30s

* Nano Banana / Nano Banana 2 / Nano Banana 2 Lite / Nano Banana Pro have less restrictive content moderation and can use photos of minors or recognizable people as reference images. Use responsibly and in compliance with applicable laws.

nano-banana-2.1 needs a Standard or higher PixVerse plan. It is not available on Basic.

Aspect Ratios

Each model accepts its own list. If aspect_ratio is omitted, the default (first column) is used. Passing a value not in the model’s row is rejected with 400.

Models Default Accepted aspect_ratio values
nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, seedream-4.0, seedream-4.5, seedream-5.0-pro, seedream-5.0-lite auto auto, 1:1, 16:9, 9:16, 4:3, 3:4, 5:4, 4:5, 3:2, 2:3, 21:9
qwen-image 1:1 1:1, 16:9, 9:16, 4:3, 3:4, 5:4, 4:5, 3:2, 2:3, 21:9
kling-o3, kling-3.0 1:1 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
gpt-image-2.0, gpt-image-2.5-flare, gpt-image-2.5-sunburst 1:1 1:1, 1:2, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 2:1, 21:9
nano-banana-2.1 auto auto, 1:1, 16:9, 9:16, 4:3, 3:4, 5:4, 4:5, 3:2, 2:3, 21:9, 1:4, 4:1, 1:8, 8:1

gpt-image-2.0 also takes the detail_level parameter (low, medium, or high). The gpt-image-2.5 pair takes it too and adds two higher tiers, xhigh and max. It affects credit cost — see the credits estimator below.

nano-banana-2.1 uses detail_level for its thinking level: minimal, medium (the default) or high. It does not change the price.

Credits estimator

Credits are charged per image. Actual costs may change, see pixverse.ai for current pricing.

Model Quality Credits per image Quantity
qwen-image 720p 5 1-4
qwen-image 1080p 10 1-4
nano-banana-2-lite 1080p 6 1-4
seedream-4.0 all 10 1-4
seedream-4.5 all 10 1-4
nano-banana 1080p 15 1-4
seedream-5.0-pro 1080p 15 1-4
seedream-5.0-pro 1440p 30 1-4
seedream-5.0-lite 1440p 12 1-4
seedream-5.0-lite 1800p 15 1-4
seedream-5.0-lite 2160p 18 1-4
nano-banana-2 512p 16 1-4
nano-banana-2 1080p 25 1-4
nano-banana-2 1440p 40 1-4
nano-banana-2 2160p 60 1-4
nano-banana-2.1 1080p 10 1-4
nano-banana-2.1 1440p 25 1-4
nano-banana-2.1 2160p 35 1-4
nano-banana-pro 1080p, 1440p 50 1-4
nano-banana-pro 2160p 90 1-4
kling-3.0 1080p, 1440p 10 1-4
kling-o3 1080p, 1440p 10 1-4
kling-o3 2160p 20 1-4
gpt-image-2.0 1080p (low / medium / high) 15 / 30 / 60 1-4
gpt-image-2.0 1440p (low / medium / high) 30 / 60 / 120 1-4
gpt-image-2.0 2160p (low / medium / high) 45 / 90 / 180 1-4
gpt-image-2.5-flare, gpt-image-2.5-sunburst 1080p (low / medium / high / xhigh / max) 5 / 5 / 15 / 20 / 50 1-4
gpt-image-2.5-flare, gpt-image-2.5-sunburst 1440p (low / medium / high / xhigh / max) 6 / 6 / 20 / 35 / 80 1-4
gpt-image-2.5-flare, gpt-image-2.5-sunburst 2160p (low / medium / high / xhigh / max) 7 / 10 / 35 / 65 / 145 1-4
Unlimited Image Generation (Relax Mode)

Pro+ subscription plans include unlimited image generation in Relax Mode for select models:

Plan Price Unlimited Models
Pro $30/m qwen-image, nano-banana-2-lite
Premium $60/m qwen-image, nano-banana, nano-banana-2, nano-banana-2.1, nano-banana-2-lite, seedream-4.0
Ultra $199/m qwen-image, nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, seedream-4.0, seedream-4.5, seedream-5.0-lite, seedream-5.0-pro, kling-3.0, kling-o3, gpt-image-2.0, gpt-image-2.5-flare, gpt-image-2.5-sunburst, nano-banana-2.1 (all 15)

You choose Relax Mode per request with the optional relax_mode parameter. Most requests should leave it out:

relax_mode Model is free on the account’s plan Model is not free on the account’s plan
left out (recommended) Free, in Relax Mode Credits at the regular price
true Free, in Relax Mode Refused with 412, nothing is charged
false Credits at the regular price, generated at full speed Credits at the regular price

When you leave relax_mode out, the API doesn’t send it to PixVerse at all, and PixVerse uses Relax Mode whenever the account’s plan makes that model free. It works on every plan and never fails because of Relax Mode. Set relax_mode: false only when you would rather pay credits than wait in Relax Mode, which PixVerse runs slower than paid generation. Set relax_mode: true only when you never want to be charged: on a model or plan without the benefit the request fails with 412 instead of spending credits.

To see what PixVerse did, check cost_credits and generation_mode on GET images/imageId.

Relax Mode is unmetered, not unthrottled. These models cost zero credits on the listed plans and nothing rejects a request for being too frequent, but PixVerse applies a daily volume threshold. Past it the account is moved to a slow queue rather than refused — generations still succeed and still cost nothing, they just take far longer to come back. It is visible in the response, where queue_data.slow_queue turns true, queue_data.reason reads daily_limit_exceeded, and queue_count gives the number of tasks ahead.

The threshold applies per model, not per account. An account throttled on one model keeps generating at full speed on every other one, and the busiest accounts clear 500–700 images a day across models combined. We have seen it engage on nano-banana-2, nano-banana-pro and gpt-image-2.0, most often on nano-banana-2. The point at which it engages is not fixed and varies between accounts, but as a rough guide expect a few hundred images per model per day — around 300 for nano-banana-pro and around 500 for gpt-image-2.0. We have not seen it on the remaining models, which does not mean they are unlimited, only that nobody has pushed them hard enough for it to show. The allowance resets at approximately 00:00 UTC, so a throttled account is clear again at the start of the next UTC day. PixVerse moves these thresholds without notice, so treat them as rough capacity guidance rather than a guarantee.

Sustained volume needs more than one account, because each account carries its own allowance and POST /videos/create and POST /images/create spread work across every account you have configured. Adding accounts alone is not a guarantee though — we have seen a multi-account pool throttled on the same model at the same time, because every account was working through the same daily allowance on the same model. Once a pool is in that state more accounts only buy one more allowance each, and none of them are fast.

Falling back to another model is usually the better move, because the allowances are independent per model. An account wedged on nano-banana-2 still generates on nano-banana-pro, seedream-4.5 or gpt-image-2.0 at full speed. Decide in advance which models are acceptable for your use case, watch for queue_data.slow_queue turning true on the image or video response, and move down that list rather than waiting out the queue.

To retrieve generated image(s), use:

To delete a generated image, use:

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

Request Headers 
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
Request Body 
{
    "email": "Optional PixVerse API account email",
    "prompt": "Required text prompt",
    "model": "seedream-4.0",
    "quality": "1080p",
    "aspect_ratio": "auto",
    "detail_level": "medium",
    "create_count": 1,
    "seed": 654321,
    "image_path_1": "upload/eb20c63d-2a1a-5be6-a562-d3578a2831e3.png",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 3
}
Parameters

  • email is optional, if not specified API will randomly select account from available accounts.

  • prompt is required, describe your image. Maximum length 20,000 characters for the Nano Banana models (nano-banana, nano-banana-2, nano-banana-2.1, nano-banana-2-lite, nano-banana-pro) and the GPT Image models (gpt-image-2.0, gpt-image-2.5-flare, gpt-image-2.5-sunburst), 5,000 characters for the other models.

  • model is optional. Default: qwen-image. See Model Comparison Matrix for the full list and per-model notes.

  • quality is optional, model-specific. Defaults to the model’s first listed value. See Model Comparison Matrix for per-model qualities.

  • aspect_ratio is optional. Each model accepts its own list — see Aspect Ratios above. If omitted, the model’s default is used. Passing a value not in the model’s row is rejected with 400.

  • detail_level is accepted by gpt-image-2.0 (low, medium, high), by gpt-image-2.5-flare / gpt-image-2.5-sunburst (low, medium, high, xhigh, max) and by nano-banana-2.1 (minimal, medium, high), and rejected for all other models. When omitted it defaults to low, or to medium for nano-banana-2.1. A value outside the model’s list is rejected with 400. For the GPT Image models it drives the credit cost. For nano-banana-2.1 it is the thinking level and the price stays the same. For gpt-image-2.0 the steps are relative (low = 0.5×, medium = 1×, high = 2× per quality). The gpt-image-2.5 pair has its own absolute price per quality and level — see the credits estimator.

  • create_count is optional. Number of images to generate per request. Supported range: 1…4, default 1.

  • seed is optional. Valid range 0…2147483647.

  • relax_mode is optional, true or false. Leave it out unless you need one of the two cases below. When it is left out, nothing is sent to PixVerse and the image is free whenever the account’s plan makes the model free (see Unlimited Image Generation), and paid with credits otherwise. false always pays credits at the regular price and generates at full speed, even when the model would be free. true asks for a free image only. If the account’s plan does not make this model free, the request is refused with 412 and no credits are spent.

  • image_path_1 through image_path_16 are optional. Reference image file paths uploaded via POST files for image-to-image (i2i) generation. Reference images must be provided sequentially — image_path_2 requires image_path_1, etc. Maximum number of references depends on the model (see Model Comparison Matrix). Only gpt-image-2.5-flare and gpt-image-2.5-sunburst reach 16. On those two models each reference adds 5 credits on top of the base price. Every other model includes its references at no extra cost.

  • replyUrl is optional, place here your callback URL. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided replyUrl once the PixVerse image is completed or failed. We recommend using sites like webhook.site to test callback URL functionality. Maximum length 1024 characters. Callback body has the same JSON shape as GET /images/image_id response.

  • replyRef is optional, place here your reference id which will be stored and returned along with this PixVerse image response / result. Maximum length 1024 characters.

  • maxJobs is optional, if not specified value from selected accounts/email will be used. It should not exceed the number of concurrent generations supported by your account subscription plan. Valid range: 1…8

Responses

  • 200 OK

    Use returned image_id or values from success_ids array to retrieve image status and results using GET images/imageId. Check image_status_name for COMPLETED and image_url for the generated image link.

    If you specify the optional parameter replyUrl, the API will call the provided replyUrl with image progress updates until the image is complete or fails.

    {
    "image_id": "user:<userid>-pixverse:<email>-image:<number>",
    "success_ids": [
        "user:<userid>-pixverse:<email>-image:<id_1>",
        "user:<userid>-pixverse:<email>-image:<id_2>"
    ],
    "success_count": 2,
    "fail_count": 0,
    "total_count": 2,
    "cost_credits": 0,
    "code": 200
}

    cost_credits is what PixVerse charged for the request, 0 for images made in Relax Mode.

  • 400 Bad Request

    {
  "error": "<Error message>"
}

  • 401 Unauthorized

    {
  "error": "Unauthorized"
}

  • 412 Precondition Failed

    The account’s PixVerse plan doesn’t allow this request. Three cases:

    1. Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. 
      {
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}
    2. The model needs a higher plan, for example nano-banana-2.1 on Basic. 
      {
  "error": "This image model is available for Standard and higher plans only. Please upgrade your membership to use this feature. (500342)"
}
    3. You sent relax_mode: true, and the account’s plan doesn’t make this model free. Nothing is charged. Leave relax_mode out to have the image paid with credits instead, see Unlimited Image Generation. 
      {
  "error": "relax_mode: true needs a PixVerse plan that includes unlimited free generation with model qwen-image, and this account's plan does not. Leave relax_mode out to generate for free whenever the plan allows it and pay credits otherwise, or set relax_mode: false to pay credits at full speed. PixVerse: Relax mode requires an active unlimited image benefit for this model. (400017)",
  "code": 412
}

  • 422 Unprocessable Content

    Moderated message.

    {
  "error": "Your prompt has triggered our AI moderator, please re-enter your prompt"
}

  • 429 Too Many Requests

    Wait in a loop for at least 10..30 seconds and retry again.

    There are two possible cases for API response 429:

    1. API query is full and can not accept new images/create requests. Size of query defined by maxJobs optional parameter. 
      {
 "error":
   "Account <email> is busy executing <maxJobs> tasks."
   "All configured accounts are running at maximum capacity."
}
    2. The API received an HTTP response status 429 from PixVerse. Please refer to your subscription plan for the maximum allowed tasks in the queue. 
      {
  "error": "Reached the limit for concurrent generations."
}

  • 596 Pending mod message

    The account has a pending error, and the API does not use it until you add it again with POST accounts/email. You receive an email when this happens. There are three causes.

    PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password.

    {
  "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.",
  "code": 596
}

    Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse’s own details in account_moderation, and later calls return the same error. Add the account again after reinstatement_at. To ask PixVerse to lift the suspension earlier, write to the support_email it gives.

    {
  "error": "PixVerse suspended account [email protected] for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to [email protected].",
  "code": 596,
  "account_moderation": {
    "ban_level": "suspend_30d",
    "action": "temporary_suspend",
    "duration_days": 30,
    "suspended_at": "2026-10-16 09:26:25 (UTC)",
    "reinstatement_at": "2026-11-15 09:26:25 (UTC)",
    "support_email": "[email protected]"
  }
}

    Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the error quotes PixVerse’s own message, which says how to appeal. Remove the account with DELETE accounts/email, or add it again only if PixVerse lifts the ban.

    {
  "error": "PixVerse banned account [email protected] for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/[email protected], or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.",
  "code": 596
}

    If every account you have is in this state, a request without email returns 596 as well.

Model 
{ // TypeScript, all fields are optional
    image_id: string
    success_ids: string[]
    success_count: number
    fail_count: number
    total_count: number
    cost_credits: number
    error: string
    code: number
}
Examples 
  • curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/images/create" \
     -d '{"prompt": "…"}'

  • const prompt = "text prompt";
const apiUrl = `https://api.useapi.net/v2/pixverse/images/create`;
const token = "API token";
const data = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({
  prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});

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