How to connect and authenticate

Step-by-step guide on using our API via WebSockets for efficient and fast connection.

Authentication

To interact with the Runware API, you need to authenticate your requests using an API key. This key is unique to your account and is used to identify you when making requests. You can create multiple keys for different projects or environments (development, production, staging) , add descriptions to them, and revoke them at any time. With the new teams feature, you can also share keys with your team members.

To create an API key, simply sign up on Runware and visit the "API Keys" page. Then, click "Create Key" and fill the details for your new key.

WebSockets

We currently support WebSocket connections as they are more efficient, faster, and less resource intensive. We have made our WebSocket connections easy to work with, as each response contains the request ID. So it's possible to easily match request → response.

REST API will be available soon, we are working on it.

The API uses a bidirectional protocol that encodes all messages as JSON objects.

To connect you can use one of the sdks we provide JavaScript, (Python or manually.

If you prefer to connect manually (to use another language/technology), the endpoint URL is wss://ws-api.runware.ai/v1.

New connections

Request

WebSocket connections are point-to-point, so there's no need for each request to contain an authentication header.

Instead, the first request must always be an authentication request that includes the API key. This way we can identify which subsequent requests are arriving from the same user.

[
  {
    "taskType": "authentication",
    "apiKey": "<APIKEY>"
  }
]

Response

After you've made the authentication request the API will return an object with the connectionSessionUUID parameter. This string is unique to your connection and is used to resume connections in case of disconnection (more on this later).

{
  "data": [
    {
      "taskType": "authentication",
      "connectionSessionUUID": "f40c2aeb-f8a7-4af7-a1ab-7594c9bf778f"
    }
  ]
}

In case of error you will receive an object with the error message.

{
  "error": true,
  "errorMessageContentId": 1212,
  "errorId": 19,
  "errorMessage": "Invalid api key"
}

Keeping connection alive

The WebSocket connection is kept open for 120 seconds from the last message exchanged. If you don't send any messages for 120 seconds, the connection will be closed automatically.

To keep the connection going, you can send a ping message when needed, to which we will reply with a pong.

[
  {
    "taskType": "ping",
    "ping": true
  }
]

{
  "data": [
    {
      "taskType": "ping",
      "pong": true
    }
  ]
}

Resuming connections

If any service, server or network is unresponsive (for instance due to a restart), all the images or tasks that could not be delivered are kept in a buffer memory for 120 seconds. You can reconnect and have these messages delivered by including the connectionSessionUUID parameter in the initial authentication connection request.

[
  {
    "taskType": "authentication",
    "apiKey": "<APIKEY>",
    "connectionSessionUUID": "f40c2aeb-f8a7-4af7-a1ab-7594c9bf778f"
  }
]

This means that is not needed to make the same request again, the initial one will be delivered when reconnecting.

SDK libraries reconnects automatically.