Skip to main content

​
Overview

All generation requests follow the same basic lifecycle: Job lifecycle diagram

​
Job States

queued Job is waiting in the queue to be processed processing Job is actively being processed by a worker completed Job finished successfully, result available in result.urls failed Job failed due to an error, details in result.error cancelled Job was cancelled by the user or system

​
Failures & Cancellation

Jobs can fail for several reasons:
  • API errors from the generation service
  • Invalid parameters or unsupported configurations
  • Content moderation (NSFW filtering)
  • Automatic timeout detection (3 minutes for hosted tools, 2 hours for external providers)
To cancel a job: Send a DELETE request to /jobs/{id}. Note: Jobs can only be canceled while they have a status of queued or processing.
Important: Failed and cancelled jobs do not consume compute units. You’re only billed for completed jobs.

​
Checking Job Status

Poll for job status using a GET request to /jobs/{id}. Recommended practices:
  • Poll every 2-5 seconds while job is pending ( queued or processing)
  • Use exponential backoff for longer-running jobs
  • Stop polling when status is completed, failed, or cancelled
  • Some jobs may include preview images in responses during processing
Example polling implementation: 
import time

def wait_for_job(job_id):
    while True:
        response = requests.get(
            f"{API_BASE}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {API_TOKEN}"}
        )
        job = response.json()

        # Check if job is terminal
        if job.get("completed_at"):
            if job["status"] == "completed":
                return job["result"]
            else:
                raise Exception(f"Job {job['status']}: {job.get('result', {}).get('error')}")

        print(f"Status: {job['status']}")
        time.sleep(2)

​
Next Steps

Webhooks

Receive notifications when jobs complete

Rate Limits

Understand API limits by plan tier

Model APIs

Explore all available endpoints and parameters

API Keys & Billing

Create and manage your API keys