> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution Modes & HTTP Queue

> How to receive job results via webhooks, WebSockets, or polling

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:

<CardGroup cols={3}>
  <Card title="Webhooks" icon="bell" href="/execution-modes-and-integrations/webhooks">
    Results pushed to your server (recommended).
  </Card>

  <Card title="WebSockets" icon="plug" href="/execution-modes-and-integrations/websockets">
    Real-time updates with live previews.
  </Card>

  <Card title="Polling" icon="rotate">
    Query `/api/v2/jobs/{id}` manually.
  </Card>
</CardGroup>

***

## Webhooks (Recommended)

<Info>
  For most integrations, use webhooks. They're the most reliable way to receive results without maintaining persistent connections or implementing polling logic.
</Info>

With webhooks, deAPI sends an HTTP POST to your server when a job completes. Configure a global webhook URL in [account settings](https://app.deapi.ai/settings/webhooks), or override per-request:

```bash theme={null}
# 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):**

```json theme={null}
{
  "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](/execution-modes-and-integrations/webhooks)

***

## WebSockets (Real-time)

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

```javascript theme={null}
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](/execution-modes-and-integrations/websockets)

***

## Polling (Fallback)

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

```bash theme={null}
# 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`)                |

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

→ [Get Job Results Endpoint Reference](/api/v2/utilities/jobs)

***

## 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    |

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

***

## How Jobs Are Processed

Every model endpoint follows the same pattern:

<Steps>
  <Step title="Submit request">
    Send `POST /api/v2/{resource}/{operation}` with your parameters (optionally include `webhook_url`).
  </Step>

  <Step title="Receive request_id">
    Response contains `request_id` for tracking.
  </Step>

  <Step title="Job queued">
    Request enters the queue with status `pending`.
  </Step>

  <Step title="Worker processes">
    GPU worker picks up the job, status becomes `processing`.
  </Step>

  <Step title="Results delivered">
    Via webhook POST, WebSocket event, or polling response.
  </Step>
</Steps>

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         |