Execution Modes & HTTP Queue

All deAPI model endpoints use an asynchronous job queue. You submit a request, receive a request_id, and retrieve results using one of three methods:

Webhooks

Results pushed to your server (recommended).

WebSockets

Real-time updates with live previews.

Polling

Query /api/v2/jobs/{id} manually.

Webhooks (Recommended)

For most integrations, use webhooks. They’re the most reliable way to receive results without maintaining persistent connections or implementing polling logic.

With webhooks, deAPI sends an HTTP POST to your server when a job completes. Configure a global webhook URL in account settings, or override per-request:

# 1. Submit job with webhook_url
curl -X POST https://api.deapi.ai/api/v2/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a beautiful sunset over mountains",
    "model": "Flux1schnell",
    "width": 1024,
    "height": 768,
    "guidance": 3.5,
    "steps": 4,
    "seed": -1,
    "webhook_url": "https://your-server.com/webhooks/deapi"
  }'

# 2. Response contains request_id
# {"data": {"request_id": "123e4567-e89b-12d3-a456-426614174000"}}

# 3. deAPI POSTs to your webhook when done

Webhook payload (job.completed):

{
  "event": "job.completed",
  "data": {
    "job_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "done",
    "job_type": "image_generation",
    "result_url": "https://storage.deapi.ai/results/.../output.png",
    "processing_time_ms": 45000
  }
}

Why webhooks:

No polling required — results arrive automatically
Automatic retries with exponential backoff (up to 10 retries over ~24 hours)
Works with serverless and traditional backends
Secure with HMAC signature verification

→ Full Webhooks Documentation

WebSockets (Real-time)

For interactive applications that need instant feedback and live previews during generation:

import Pusher from 'pusher-js';

const pusher = new Pusher('depin-api-prod-key', {
    wsHost: 'soketi.deapi.ai',
    wsPort: 443,
    forceTLS: true,
    cluster: 'mt1',
    enabledTransports: ['ws', 'wss'],
    authorizer: (channel) => ({
        authorize: async (socketId, callback) => {
            const res = await fetch('https://api.deapi.ai/broadcasting/auth', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${API_TOKEN}`
                },
                body: JSON.stringify({ socket_id: socketId, channel_name: channel.name })
            });
            callback(null, await res.json());
        }
    })
});

pusher.subscribe(`private-client.${CLIENT_ID}`)
    .bind('request.status.updated', (data) => {
        console.log(`Job ${data.request_id}: ${data.status} (${data.progress}%)`);
        if (data.preview) displayPreview(data.preview);
        if (data.result_url) downloadResult(data.result_url);
    });

Why WebSockets:

Instant updates (milliseconds latency)
Live preview images during generation
Progress percentage updates
Ideal for user-facing UIs

→ Full WebSockets Documentation

Polling (Fallback)

If webhooks or WebSockets aren’t feasible, poll the status endpoint:

# 1. Submit job (without webhook_url)
curl -X POST https://api.deapi.ai/api/v2/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a beautiful sunset",
    "model": "Flux1schnell",
    "width": 512,
    "height": 512,
    "guidance": 3.5,
    "steps": 4,
    "seed": -1
  }'

# Response: {"data": {"request_id": "abc123..."}}

# 2. Poll for results
curl https://api.deapi.ai/api/v2/jobs/abc123 \
  -H "Authorization: Bearer $API_KEY"

Response fields:

Field	Description
`status`	`pending`, `processing`, `done`, or `error`
`progress`	Progress percentage (when available)
`result_url`	Download URL (when `done`)
`error`	Error details (when `error`)

Polling adds latency, wastes resources with unnecessary requests, and provides no live previews. Use webhooks or WebSockets when possible.

→ Get Job Results Endpoint Reference

Choosing a Method

Scenario	Recommended
Backend service / serverless	Webhooks
Interactive web app with progress UI	WebSockets
Simple scripts / CLI tools	Polling
Mobile app with real-time updates	WebSockets
Batch processing pipeline	Webhooks

Use webhooks as your primary method with WebSockets for UI updates. This gives you reliability (webhook retries) plus great UX (instant progress).

How Jobs Are Processed

Every model endpoint follows the same pattern:

Submit request

Send POST /api/v2/{resource}/{operation} with your parameters (optionally include webhook_url).

Receive request_id

Response contains request_id for tracking.

Job queued

Request enters the queue with status pending.

Worker processes

GPU worker picks up the job, status becomes processing.

Results delivered

Via webhook POST, WebSocket event, or polling response.

This queued model:

Keeps long-running jobs off the HTTP request path
Avoids timeout issues for video/audio generation
Enables efficient GPU scheduling across the distributed network
Provides a consistent pattern across all endpoints

Quick Reference

Endpoint	Description
`POST /api/v2/{resource}/{operation}`	Submit a job
`GET /api/v2/jobs/{request_id}`	Check job status (polling)
`POST {your_webhook_url}`	Receive webhook notification
`wss://soketi.deapi.ai`	WebSocket connection

Get started

Execution Modes & Integrations

Other

Execution Modes & HTTP Queue

Webhooks

WebSockets

Polling

Webhooks (Recommended)

WebSockets (Real-time)

Polling (Fallback)

Choosing a Method

How Jobs Are Processed

Quick Reference

Webhooks

WebSockets

Polling

​Webhooks (Recommended)

​WebSockets (Real-time)

​Polling (Fallback)

​Choosing a Method

​How Jobs Are Processed

​Quick Reference

Webhooks (Recommended)

WebSockets (Real-time)

Polling (Fallback)

Choosing a Method

How Jobs Are Processed

Quick Reference