Retrieve Image Job Status

March 2, 2026 (November 16, 2026)

Table of contents

  1. Request Headers
  2. Path Parameters
  3. Responses
  4. Model
    1. Some images failed
    2. Watermark
  5. Examples
  6. Try It

Retrieve the status and result of an image generation or upscale job by its job ID.

Use this endpoint to poll for completion after submitting an image via POST /images or POST /images/upscale. Jobs are retained for 30 days.

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

Request Headers

Authorization: Bearer {API token}

Path Parameters

Responses

  • 200 OK

    Returns the job record with current status and details.

    Processing (status: created):

    {
      "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",
        "model": "seedream-4.0",
        "ratio": "16:9",
        "resolution": "2k",
        "inputMode": "generate"
      },
      "response": {
        "forecastCost": 0
      },
      "code": 200
    }
    

    Completed (image generation):

    {
      "jobid": "j0302140530123456789i-u12345-US:[email protected]:dreamina",
      "type": "image",
      "status": "completed",
      "model": "seedream-4.0",
      "created": "2026-03-02T14:05:30.123Z",
      "updated": "2026-03-02T14:06:06.789Z",
      "request": {
        "prompt": "A stunning aurora borealis over a frozen lake",
        "model": "seedream-4.0",
        "ratio": "16:9",
        "resolution": "2k",
        "inputMode": "generate"
      },
      "response": {
        "images": [
          {
            "imageUrl": "https://p9-sign.douyinpic.com/...",
            "imageUri": "tos-useast5-i-wopfjsm1ax-tx/abc123",
            "width": 2560,
            "height": 1440,
            "format": "jpeg",
            "assetId": "US:[email protected]:7612453183683579150",
            "assetRef": "US:[email protected]:w2560:h1440:s905000-uri:tos-useast5-i-wopfjsm1ax-tx/abc123",
            "itemId": "7612453183683579150"
          },
          {
            "imageUrl": "https://p9-sign.douyinpic.com/...",
            "imageUri": "tos-useast5-i-wopfjsm1ax-tx/def456",
            "width": 2560,
            "height": 1440,
            "format": "jpeg",
            "assetId": "US:[email protected]:7612453183683595534",
            "assetRef": "US:[email protected]:w2560:h1440:s911000-uri:tos-useast5-i-wopfjsm1ax-tx/def456",
            "itemId": "7612453183683595534"
          }
        ],
        "forecastCost": 0,
        "historyRecordId": "306191111942",
        "finishTime": 1709391966
      },
      "code": 200
    }
    

    Completed (upscale):

    {
      "jobid": "j0302140630123456789I-u12345-US:[email protected]:dreamina",
      "type": "upscale",
      "status": "completed",
      "model": "seedream-4.0",
      "created": "2026-03-02T14:06:30.123Z",
      "updated": "2026-03-02T14:08:07.456Z",
      "request": {
        "jobid": "j0302140530123456789i-u12345-US:[email protected]:dreamina",
        "imageIndex": 0,
        "resolution": "4k"
      },
      "response": {
        "images": [
          {
            "imageUrl": "https://p9-sign.douyinpic.com/...",
            "imageUri": "tos-useast5-i-wopfjsm1ax-tx/upscaled123",
            "width": 4096,
            "height": 4096,
            "format": "jpeg",
            "assetId": "US:[email protected]:7612453244173880589",
            "assetRef": "US:[email protected]:w4096:h4096:s1482000-uri:tos-useast5-i-wopfjsm1ax-tx/upscaled123",
            "itemId": "7612453244173880589"
          }
        ],
        "forecastCost": 0,
        "historyRecordId": "306191137798",
        "finishTime": 1709392087
      },
      "code": 200
    }
    

    Note: The assetRef on each image can be used directly as imageRef_N in POST /images for further generations, without needing to re-upload.

    Failed:

    {
      "jobid": "j0302140530123456789i-u12345-US:[email protected]:dreamina",
      "type": "image",
      "status": "failed",
      "model": "seedream-4.0",
      "created": "2026-03-02T14:05:30.123Z",
      "updated": "2026-03-02T14:07:15.456Z",
      "request": {
        "prompt": "A test prompt",
        "model": "seedream-4.0",
        "ratio": "16:9",
        "resolution": "2k",
        "inputMode": "generate"
      },
      "error": "fail_code: 2050",
      "errorDetails": "The prompt may contain content that violates our Community Guidelines. Change it and try again.",
      "failMsg": "InputTextCopyright",
      "code": 2050
    }
    

    Jobs still created 2 hours after they were submitted are marked as failed with "Generation timed out after 120m (…)" (code 408).

    errorDetails is the sentence Dreamina’s website shows, and it reads the same for different filters. failMsg is Dreamina’s own name for the failure, so you can tell them apart. Common values, all raised after submission — a job that fails this way is not charged:

    code failMsg Meaning Retry?
    2038 InputTextRisk Dreamina’s content filter refused the prompt No: change the prompt
    2050 InputTextCopyright The prompt names something Dreamina treats as protected, such as a brand, a character or a state symbol No: change the prompt
    2039 InputImageRisk Dreamina’s content filter refused a reference image No: replace the image
    2048 InputImageCopyright A reference image looks like protected content No: replace the image
    2041 OutputImageRisk The generated image failed moderation No: change the prompt
    23004 common error Dreamina failed without naming a reason Yes: Dreamina’s side failed
    8810000 ArkOther Dreamina’s model service failed Yes: Dreamina’s side failed
  • 401 Unauthorized

    Invalid API token.

    {
      "error": "Unauthorized"
    }
    
  • 403 Forbidden

    The job belongs to a different useapi.net user.

    {
      "error": "No access to account US:[email protected]",
      "code": 403
    }
    
  • 404 Not Found

    Job not found, or it has expired (>30 days). The response has no body.

Model

The image job with its status: a completed job lists its images in response.images, and a failed one carries error and code.

The image job record for each status, field by field, and notes on partial results and the watermark
  • Image generation completed. Includes image URLs and metadata.

    {
      jobid: string                    // Unique job identifier
      type: 'image' | 'upscale'       // Job type
      status: 'completed'
      model: string                    // Model used
      created: string                  // ISO 8601 timestamp
      updated: 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
        jobid?: string                 // Source job (upscale only)
        imageIndex?: number            // Source image index (upscale only)
        replyUrl?: string
        replyRef?: string
      }
    
      response: {
        images: Array<{
          imageUrl: string             // Direct image URL (JPEG)
          imageUri: string             // Native URI
          width: number                // Image width in pixels
          height: number               // Image height in pixels
          format: string               // "jpeg"
          assetId: string              // Asset identifier
          assetRef: string             // Can be used as imageRef_N in POST /images
          itemId: string               // Upstream item ID
          coverUrl?: string            // Small preview of the image, can carry the AI badge, see Watermark
        }>
        forecastCost: number           // Estimated generation time in seconds, NOT a price
        historyRecordId: string        // Upstream history record
        finishTime: number             // Unix timestamp of completion
        failedCount?: number           // Only when some of the requested images failed: how many (the rest are in images)
        failCode?: string              // Dreamina's code for those, e.g. "23001"
      }
    
      code: number                     // 200
    }
    
  • Image generation failed. Includes error details.

    {
      jobid: string
      type: 'image' | 'upscale'
      status: 'failed'
      model: string
      created: string
      updated: string
    
      request: {
        prompt?: string
        model?: string
        ratio?: string
        resolution?: string
        inputMode?: string
        replyUrl?: string
        replyRef?: string
      }
    
      error: string                    // Error summary
      errorDetails?: string            // Additional details (the sentence Dreamina's website shows)
      failMsg?: string                 // Dreamina's own name for a failure, e.g. "InputTextCopyright", "common error"
      code: number                     // Error code
    }
    

    Common error codes:

    Code Meaning
    408 Generation timed out (no result after 2 hours)
    596 Account session expired
    2038 Content filtered
    2057 Upstream processing error

Some images failed

Dreamina sometimes finishes a request with fewer images than asked: for example 3 of 4, with the fourth failing under its code 23001 (“common error”). The job is then completed with the images that were made, and response.failedCount and response.failCode say how many failed and why. Dreamina charges only the images it delivered and returns the credits of the failed ones. Sending the same request again usually gives a full set.

Watermark

Dreamina adds an “AI” badge to the top-left corner of generated images unless the account’s “close watermark” setting is on. We switch that setting on when you add or re-add an account with POST accounts.

  • On a paid Dreamina plan, imageUrl is the clean image. On some paid accounts Dreamina keeps the badge on its preview even with the setting on. For those, imageUrl is the clean copy that Dreamina’s own Download button saves, at no extra cost.
  • coverUrl is a small preview of the image and can still carry the badge, so use imageUrl for the picture you keep or show.
  • Dreamina doesn’t allow the setting on free accounts, so their images keep the badge, in imageUrl too.
  • The URLs are signed, so editing one to remove the badge does not work.

Examples

  • curl "https://api.useapi.net/v1/dreamina/images/j0302140530123456789i-u12345-US:[email protected]:dreamina" \
      -H "Authorization: Bearer YOUR_API_TOKEN"
    
  • const apiToken = 'YOUR_API_TOKEN'
    const jobId = 'j0302140530123456789i-u12345-US:[email protected]:dreamina'
    
    async function waitForImages(jobId, intervalMs = 10000) {
      while (true) {
        const response = await fetch(`https://api.useapi.net/v1/dreamina/images/${jobId}`, {
          headers: { 'Authorization': `Bearer ${apiToken}` }
        })
        const job = await response.json()
        console.log(`Status: ${job.status}`)
    
        if (job.status === 'completed') {
          job.response.images.forEach((img, i) =>
            console.log(`  [${i}] ${img.width}x${img.height} ${img.format}`)
          )
          return job
        }
    
        if (job.status === 'failed') throw new Error(job.error)
    
        await new Promise(resolve => setTimeout(resolve, intervalMs))
      }
    }
    
    const job = await waitForImages(jobId)
    
  • import requests
    import time
    
    api_token = 'YOUR_API_TOKEN'
    job_id = 'j0302140530123456789i-u12345-US:[email protected]:dreamina'
    
    def wait_for_images(job_id: str, interval_sec: int = 10) -> dict:
        while True:
            job = requests.get(
                f'https://api.useapi.net/v1/dreamina/images/{job_id}',
                headers={'Authorization': f'Bearer {api_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['format']}")
    
                    # Download image
                    img_response = requests.get(img['imageUrl'])
                    with open(f'image_{i}.jpeg', 'wb') as f:
                        f.write(img_response.content)
                return job
    
            if job['status'] == 'failed':
                raise Exception(f"Job failed: {job.get('error')}")
    
            time.sleep(interval_sec)
    
    job = wait_for_images(job_id)
    

Try It