Skip to content

Provider WebSocket Protocol

Providers connect to the gateway using a reverse WebSocket so no inbound ports are required.

Connection

GET /ws/provider?key=ccn_sk_...
Upgrade: websocket

The gateway authenticates the API key and then waits for a ready message.

Provider → Gateway Messages

1) Ready

Sent immediately after connection:

{
  "type": "ready",
  "workflows": ["wf_id_1", "wf_id_2"],
  "gpu_info": { "name": "RTX 4090", "vram_gb": 24 },
  "workflow_meta": [
    {
      "id": "wf_id_1",
      "title": "FLUX T2I",
      "emoji": "🖼️",
      "provider_price_cents": 100,
      "showcase_images": ["/api/v1/showcase/..."],
      "cover_image": "/api/v1/covers/..."
    }
  ]
}

2) Progress

{ "type": "progress", "job_id": "...", "progress": 0.42 }

3) Preview

{ "type": "preview", "job_id": "...", "image": "<base64>", "mime": "image/jpeg" }

4) Complete

{
  "type": "complete",
  "job_id": "...",
  "output": "<base64>",
  "output_type": "image/png",
  "resolved_seeds": { "5.seed": 12345 }
}

5) Failed

{ "type": "failed", "job_id": "...", "error": "message" }

6) Update Workflows

{ "type": "update_workflows", "workflows": ["wf_id"], "workflow_meta": [ ... ] }

Gateway → Provider Messages

Job Dispatch

{
  "type": "job",
  "job_id": "...",
  "workflow_id": "wf_id_1",
  "inputs": {
    "13.text": "a glowing aurora",
    "5.seed": -1
  }
}

Ping / Pong

{ "type": "ping" }
{ "type": "pong" }

Timeouts

  • Provider job timeout: 600s
  • Providers must send heartbeats or any message within 120s to be considered online.