Generate Images

March 2, 2026

Table of contents

  1. US Models
  2. Request Headers
  3. Request Body
  4. Responses
  5. Model
  6. Examples
  7. 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.

Each generation produces up to 4 images. Generation typically completes within 15-120 seconds depending on the model and resolution.

US Models

Model Resolutions Default Max Refs Prompt Required Auto Ratio
seedream-4.5 2k, 4k 2k 6 No
(imageRef_x only)		 Yes
seedream-4.1 2k, 4k 2k 6 No
(imageRef_x only)		 Yes
seedream-4.0
(default, free)		 2k, 4k 2k 6 No
(imageRef_x only)		 Yes
nano-banana 1k 1k 3 Yes Yes
seedream-3.0 1k, 2k 1k 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.0",
  "ratio": "16:9",
  "resolution": "2k"
}
  • account is optional. Specific account to use. Auto-selected (random with available capacity) if omitted. Not needed when imageRef_N provided — account is derived from the reference.
  • prompt is required, optional when model supports imageRef_N. Maximum 1600 characters.
  • model is optional, see US 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 Model Capabilities). Supported values: 1k, 2k, 4k.
  • imageRef_1…imageRef_6 are optional. Reference images from POST /assets/account or completed image job assetRef. Must be contiguous, max per model see US Models.
  • imageStrength is optional, reference image influence strength (0-1, default: 0.5).
  • replyUrl is optional, webhook URL for job status callbacks.
  • replyRef is optional, custom reference string passed back in webhook callbacks.
  • maxJobs is optional, override max concurrent jobs for this request (1-50).

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.0",
  "created": "2026-03-02T14:05:30.123Z",
  "request": {
    "prompt": "A stunning aurora borealis over a frozen lake at midnight",
    "model": "seedream-4.0",
    "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-4.5, seedream-4.1, seedream-4.0, nano-banana, seedream-3.0"
}

  • 401 Unauthorized

    Invalid API token.

    {
  "error": "Unauthorized"
}

  • 429 Too Many Requests

    All accounts at maximum capacity.

    {
  "error": "All accounts at capacity"
}

Model 

{
  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 credit cost
  }
  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.0",
       "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.0',
    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.0',
    '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