Skip to main content

Asynchronous Job Lifecycle

All generation tasks in the AetherAI API are processed asynchronously. After creating a job, you must poll to check its status.

Job Creation​

When you send a POST request, a job_id is returned immediately. Image processing occurs in the background.

Request Example​

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/image" \
-H "Authorization: Bearer your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
  "prompt": "A beautiful sunset over mountains",
  "ai_model": "GPT Image 1.5"
}'

Response Example​

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

Job Status Polling​

Send a GET request with the returned job_id to check the job status.

curl -X GET "https://api.aetherforgeai.com/public/v1/job/{job_id}" \
-H "Authorization: Bearer your_api_key_here"

Status Values​

StatusDescription
PendingThe job is queued or being processed
SucceedThe job completed successfully
FailedAn error occurred during job processing

Response Examples by Status​

Pending​

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "Pending",
  "image_urls": []
}

Succeed​

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "Succeed",
  "image_urls": [
    "https://cdn.aetherforgeai.com/images/abc123.png",
    "https://cdn.aetherforgeai.com/images/abc123.gif"
  ]
}

Failed​

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "Failed",
  "image_urls": []
}

Polling Strategy​

We recommend polling at the following intervals to check for job completion:

  • Initial poll: 1 second after job creation
  • Subsequent intervals: 2-5 seconds
  • Maximum polling time: 1 minute (varies by job type)

Python Example​

import time
import requests

def poll_job_status(job_id, api_key, max_attempts=60):
    headers = {"Authorization": f"Bearer {api_key}"}

    for attempt in range(max_attempts):
        response = requests.get(
            f"https://api.aetherforgeai.com/public/v1/job/{job_id}",
            headers=headers
        )
        data = response.json()

        if data["status"] == "Succeed":
            return data["image_urls"]
        elif data["status"] == "Failed":
            raise Exception(f"Job failed: {data.get('error_message', 'Unknown error')}")

        time.sleep(2)

    raise TimeoutError("Job polling timed out")