Execution Modes & HTTP Queue

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

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

Results pushed to your server (recommended).

WebSockets - Real-time updates with live previews.

Query /request-status manually.

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.

With webhooks, dryAPI 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.dryapi.dev/api/v1/client/txt2img \
  -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/dryapi"
  }'

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

# 3. dryAPI 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": "txt2img",
    "result_url": "https://storage.dryapi.dev/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('dryapi-api-prod-key', {
    wsHost: 'soketi.dryapi.dev',
    wsPort: 443,
    forceTLS: true,
    cluster: 'mt1',
    enabledTransports: ['ws', 'wss'],
    authorizer: (channel) => ({
        authorize: async (socketId, callback) => {
            const res = await fetch('https://api.dryapi.dev/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.dryapi.dev/api/v1/client/txt2img \
  -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.dryapi.dev/api/v1/client/request-status/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.

→ Get 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

TIP

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/v1/client/{task} 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/v1/client/{task}`	Submit a job
`GET /api/v1/client/request-status/{request_id}`	Check job status (polling)
`POST {your_webhook_url}`	Receive webhook notification
`wss://soketi.dryapi.dev`	WebSocket connection

Last updated on 21 March 2026

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

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

Results pushed to your server (recommended).

WebSockets - Real-time updates with live previews.

Query /request-status manually.

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.

With webhooks, dryAPI 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.dryapi.dev/api/v1/client/txt2img \
  -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/dryapi"
  }'

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

# 3. dryAPI 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": "txt2img",
    "result_url": "https://storage.dryapi.dev/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('dryapi-api-prod-key', {
    wsHost: 'soketi.dryapi.dev',
    wsPort: 443,
    forceTLS: true,
    cluster: 'mt1',
    enabledTransports: ['ws', 'wss'],
    authorizer: (channel) => ({
        authorize: async (socketId, callback) => {
            const res = await fetch('https://api.dryapi.dev/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.dryapi.dev/api/v1/client/txt2img \
  -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.dryapi.dev/api/v1/client/request-status/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.

→ Get 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

TIP

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

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/v1/client/{task}`	Submit a job
`GET /api/v1/client/request-status/{request_id}`	Check job status (polling)
`POST {your_webhook_url}`	Receive webhook notification
`wss://soketi.dryapi.dev`	WebSocket connection

Last updated on 21 March 2026

Execution Modes & HTTP Queue

Webhooks (Recommended)

WebSockets (Real-time)

Polling (Fallback)

Choosing a Method

How Jobs Are Processed

Submit request

Receive request_id

Job queued

Worker processes

Results delivered

Quick Reference

On this page

Execution Modes & HTTP Queue

Webhooks (Recommended)

WebSockets (Real-time)

Polling (Fallback)

Choosing a Method

How Jobs Are Processed

Submit request

Receive request_id

Job queued

Worker processes

Results delivered

Quick Reference

On this page