Generate Images

March 4, 2026 (November 18, 2026)

Table of contents

  1. Models
  2. Request Headers
  3. Request Body
  4. Unlimited
  5. Responses
  6. Model
  7. Examples
  8. Try It

Generate images using Dreamina AI models from text prompts with optional reference images. All image generation is asynchronous — this endpoint returns immediately with a job ID. Poll GET /images/jobid for completion, or use replyUrl webhook for automatic callbacks.

The Images column shows how many images a request makes, with the range count accepts in brackets. Generation typically completes within 15-120 seconds depending on the model and resolution.

Models

Model Region Images Resolutions Max Refs Prompt Required Auto Ratio
gpt-image-2.5-flare US, CA 1 1k (default), 2k, 4k 6 No
(imageRef_x only)
No
gpt-image-2.5-sunburst US, CA 1 1k (default), 2k, 4k 6 No
(imageRef_x only)
No
nano-banana-pro US, CA 1 (1–4) 1k (default), 2k, 4k 6 No
(imageRef_x only)
No
nano-banana-2.1 CA 2 (1–4) 1k (default), 2k, 4k 6 No
(imageRef_x only)
No
gpt-image-2 US, CA 1 1k (default), 2k, 4k 6 No
(imageRef_x only)
No
seedream-5.5 CA 4 (1–8) 1.5k (default), 2k 6 No
(imageRef_x only)
Yes
seedream-5.0-pro US, CA 4 (1–4) 1.5k (CA only), 2k (default), 4k 6 No
(imageRef_x only)
Yes
seedream-5.0-flash US 4 (1–4) 1.5k, 2k (default), 4k 6 No
(imageRef_x only)
Yes
seedream-5.0-lite CA 4 (1–8) 2k (default), 4k 6 No
(imageRef_x only)
Yes
seedream-4.7 CA 4 (1–8) 2k (default), 4k 6 No
(imageRef_x only)
Yes
seedream-4.6
(default model, runs on a free account’s daily credits)
US, CA 4 (1–8) 2k (default), 4k 6 No
(imageRef_x only)
Yes
seedream-4.5 US, CA 4 (1–8, US 1–4) 2k (default), 4k 6 No
(imageRef_x only)
Yes
seedream-4.1 US, CA 4 (1–8, US 1–4) 2k (default), 4k 6 No
(imageRef_x only)
Yes
seedream-4.0 US, CA 4 (1–8) 2k (default), 4k 6 No
(imageRef_x only)
Yes
seedream-3.1 CA 4 1k (default), 2k 0
(text only)
Yes No
seedream-3.0 US, CA 4 1k (default), 2k (2k without imageRef_x only) 1 Yes No

https://api.useapi.net/v1/dreamina/images

Request Headers

Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data

Request Body

{
  "prompt": "A stunning aurora borealis over a frozen lake at midnight",
  "model": "seedream-4.6",
  "ratio": "16:9",
  "resolution": "2k"
}
  • account is optional. Specific account to use. If omitted, a random account with free capacity is picked among those whose region offers model. Not needed when imageRef_N provided — account is derived from the reference.
  • prompt is required, optional when model supports imageRef_N. Maximum 5000 characters.
  • model is optional, see Models above.
  • ratio is optional, image aspect ratio (default: auto for models that support it, 1:1 otherwise). Supported values: auto, 1:1, 3:4, 16:9, 4:3, 9:16, 2:3, 3:2, 21:9.
  • resolution is optional, output resolution tier (default depends on model, see Models). Supported values: 1k, 1.5k, 2k, 4k. 1.5k is offered by seedream-5.5, seedream-5.0-flash and seedream-5.0-pro (CA).
  • background is optional, auto (default), opaque or transparent. Supported by seedream-5.5, gpt-image-2, gpt-image-2.5-flare and gpt-image-2.5-sunburst. transparent returns PNG images with a transparent background, the Transparent option in Dreamina’s image settings.
  • imageRef_1…imageRef_6 are optional. Reference images from POST /assets/account or completed image job assetRef. Must be contiguous, max per model see Models.
  • imageStrength is optional, reference image influence strength (0-1, default: 0.5).
  • count is optional, the number of images to make, within the model’s range in the Images column of Models. Each image is charged.
  • unlimited is optional, true makes the images in Dreamina’s Unlimited mode, at no credits. Models, resolutions and answers: Unlimited below.
  • replyUrl is optional, webhook URL for job status callbacks. Callback body has the same JSON shape as GET /images/jobid response.
  • replyRef is optional, custom reference string passed back in webhook callbacks.
  • maxJobs is optional, override max concurrent jobs for this request (1-50).

Unlimited

With unlimited set to true the job uses no credits. Unlimited comes with a Dreamina plan bought or upgraded during Dreamina’s November 2026 offers. Dreamina decides which of these models and resolutions an account gets and for how many days, and can end it early.

Model Unlimited at Per request Accounts
seedream-5.5 1.5K, 2K up to 4 images CA
gpt-image-2.5-flare
gpt-image-2.5-sunburst
1K, 2K 1 image US, CA
nano-banana-pro 1K, 2K up to 4 images US, CA
nano-banana-2.1 1K, 2K up to 4 images CA
  • The plan decides which of these resolutions are Unlimited. 4K never is.
  • An image request without count asks for the most the model allows, 4 images (1 on GPT Image 2.5).
  • Dreamina runs one Unlimited job at a time per account, videos and images together.
Answer When
400 A model not in the table.
412 The account has no Unlimited for this model and resolution, or it has ended. Send the request without unlimited to use credits.
429 The account is already running an Unlimited job. Retry after it finishes.

Responses

  • 200 OK

    Job created successfully. Images are generating in the background.

    {
      "jobid": "j0302140530123456789i-u12345-US:[email protected]:dreamina",
      "type": "image",
      "status": "created",
      "model": "seedream-4.6",
      "created": "2026-03-02T14:05:30.123Z",
      "request": {
        "prompt": "A stunning aurora borealis over a frozen lake at midnight",
        "model": "seedream-4.6",
        "ratio": "16:9",
        "resolution": "2k",
        "inputMode": "generate",
        "replyUrl": "https://your-domain.com/webhook",
        "replyRef": "my-ref-123"
      },
      "response": {
        "forecastCost": 0
      },
      "code": 200
    }
    

    Poll GET /images/jobid for completion status, or use replyUrl for webhook callbacks.

  • 400 Bad Request

    Validation error.

    {
      "error": "Parameter model (invalid-model) valid values: seedream-5.5, seedream-5.0-pro, seedream-5.0-flash, seedream-5.0-lite, seedream-4.7, seedream-4.6, seedream-4.5, seedream-4.1, seedream-4.0, seedream-3.1, seedream-3.0, gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst, nano-banana-pro, nano-banana-2.1"
    }
    
  • 401 Unauthorized

    Invalid API token.

    {
      "error": "Unauthorized"
    }
    
  • 412 Precondition Failed

    The Dreamina account does not have enough credits for this job (ret 1006), or unlimited was set and the account has no Unlimited for this model and resolution, or it has ended (ret 1311). Top up the account, send the request without unlimited, or use another account.

    {
      "error": "Account CA:[email protected] has no Unlimited generations left for seedream-5.5 at this resolution: Dreamina's Unlimited is a promotion benefit per account, model and resolution (the plan decides which, never 4K), and it also ends. Send the request without unlimited (it then uses credits), at a resolution the account's Unlimited covers, or on an account whose Unlimited is still active. Dreamina: Unlimited generations have ended. Future generations will use credits.",
      "code": 412,
      "ret": "1311",
      "errmsg": "Unlimited generations have ended. Future generations will use credits.",
      "failCode": "1311",
      "failStarlingMessage": "Unlimited generations have ended. Future generations will use credits.",
      "account": "CA:[email protected]",
      "model": "seedream-5.5"
    }
    
  • 429 Too Many Requests

    All accounts at maximum capacity. Wait for current jobs to complete or increase maxJobs. When you set account, or only one of your accounts can take the job, the message names that account instead: Account <account> is busy executing <N> tasks.

    {
      "error": "All configured accounts are running at maximum capacity",
      "code": 429
    }
    

Model

The new job’s jobid with status created: poll it with GET /images/jobid until it completes or fails.

The new image job, field by field
{
  jobid: string                    // Unique job identifier
  type: 'image'                    // Job type
  status: 'created'                // Initial status
  model: string                    // Model used
  created: string                  // ISO 8601 timestamp
  request: {
    prompt?: string
    model: string
    ratio?: string
    resolution?: string
    inputMode: string              // Auto-detected from params
    imageRef_1?: string            // Reference image assetRef (when provided)
    imageRef_2?: string
    imageRef_3?: string
    replyUrl?: string
    replyRef?: string
  }
  response: {
    forecastCost: number           // Estimated generation time in seconds, NOT a price
  }
  code: number                     // HTTP status code
  error?: string
}

Examples

  • # Text-to-image
    curl -X POST \
         -H "Authorization: Bearer YOUR_API_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
           "prompt": "A stunning aurora borealis over a frozen lake",
           "model": "seedream-4.6",
           "ratio": "16:9",
           "resolution": "2k"
         }' \
         "https://api.useapi.net/v1/dreamina/images"
    
    # With reference image
    curl -X POST \
         -H "Authorization: Bearer YOUR_API_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
           "prompt": "A dreamy reinterpretation with soft pastel colors",
           "model": "seedream-4.1",
           "imageRef_1": "US:[email protected]:w685:h900:s86866-uri:tos-useast5-i-wopfjsm1ax-tx/abc123",
           "imageStrength": 0.5
         }' \
         "https://api.useapi.net/v1/dreamina/images"
    
  • const token = 'YOUR_API_TOKEN';
    const apiUrl = 'https://api.useapi.net/v1/dreamina/images';
    
    // Text-to-image
    const response = await fetch(apiUrl, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt: 'A stunning aurora borealis over a frozen lake',
        model: 'seedream-4.6',
        ratio: '16:9',
        resolution: '2k'
      })
    });
    
    const result = await response.json();
    console.log('Job created:', result.jobid);
    
    // Poll for completion
    const poll = async (jobid) => {
      while (true) {
        const res = await fetch(`https://api.useapi.net/v1/dreamina/images/${jobid}`, {
          headers: { 'Authorization': `Bearer ${token}` }
        });
        const job = await res.json();
        console.log('Status:', job.status);
    
        if (job.status === 'completed') {
          console.log('Images:', job.response.images.length);
          job.response.images.forEach((img, i) =>
            console.log(`  [${i}] ${img.width}x${img.height} ${img.imageUrl}`)
          );
          return job;
        }
        if (job.status === 'failed') throw new Error(job.error);
    
        await new Promise(r => setTimeout(r, 10000));
      }
    };
    
    const completed = await poll(result.jobid);
    
  • import requests
    import time
    
    token = 'YOUR_API_TOKEN'
    api_url = 'https://api.useapi.net/v1/dreamina/images'
    
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    
    # Text-to-image
    data = {
        'prompt': 'A stunning aurora borealis over a frozen lake',
        'model': 'seedream-4.6',
        'ratio': '16:9',
        'resolution': '2k'
    }
    
    response = requests.post(api_url, headers=headers, json=data)
    result = response.json()
    print(f"Job created: {result['jobid']}")
    
    # Poll for completion
    jobid = result['jobid']
    while True:
        job = requests.get(
            f'https://api.useapi.net/v1/dreamina/images/{jobid}',
            headers={'Authorization': f'Bearer {token}'}
        ).json()
        print(f"Status: {job['status']}")
    
        if job['status'] == 'completed':
            for i, img in enumerate(job['response']['images']):
                print(f"  [{i}] {img['width']}x{img['height']} {img['imageUrl']}")
            break
        if job['status'] == 'failed':
            raise Exception(job.get('error'))
    
        time.sleep(10)
    

Try It