README

A lightweight, framework-agnostic PHP SDK for Runware — covering REST and WebSocket flows, with conveniences for image generation, uploads, model search, captioning, and async polling.

Status: Community SDK (unofficial). Built for PHP ≥ 8.1.

Installation

composer require atcipher/runware-php-sdk

You may also need to add the SDK via VCS until it’s on Packagist:

composer config repositories.atcipher-runware vcs https://github.com/atcipher/runware-php-sdk
composer require atcipher/runware-php-sdk:dev-main

Quickstart (REST)

use Atcipher\Runware\RunwareClient;

$client = new RunwareClient($_ENV['RUNWARE_API_KEY']);

// Text → Image
$res = $client->textToImage(
    prompt: 'a serene mountain lake at sunrise, ultra-detailed',
    model: 'runware:101@1',
    width: 1024,
    height: 1024,
    options: ['steps' => 30, 'CFGScale' => 7.5, 'numberResults' => 1]
);

// The API may return `data` as an array or an object depending on the endpoint.
// Handle both shapes:
$imageUrl = null;
if (isset($res['data'][0]['imageURL'])) {
    $imageUrl = $res['data'][0]['imageURL'];
} elseif (isset($res['data']['imageURL'])) {
    $imageUrl = $res['data']['imageURL'];
}
echo $imageUrl, PHP_EOL;

Image → Image (upload then transform)

// Upload a local file or public URL (data URI / base64 also supported)
$upload = $client->uploadImage('https://example.com/photo.jpg');
$seedUUID = $upload['data']['imageUUID'] ?? null;

$gen = $client->imageToImage(
    prompt: 'watercolor style',
    seedImage: $seedUUID,
    model: 'civitai:139562@297320',
    width: 1024,
    height: 1024,
    options: ['strength' => 0.7]
);

Model search

$models = $client->modelSearch([
    'search'       => 'photorealistic',
    'category'     => 'checkpoint',
    'architecture' => 'sdxl',
    'limit'        => 5,
]);

Caption an image (image → text)

$caption = $client->imageCaption($seedUUID, ['includeCost' => true]);
$text = $caption['data'][0]['text'] ?? ($caption['data']['text'] ?? '');

Async workflows (polling)

// Send your initial task with "deliveryMethod":"async" in the options.
// Later, poll:
$taskUUID = '...'; // UUID you used on the async task
$status = $client->getResponse($taskUUID);

WebSocket usage (optional)

use Atcipher\Runware\{Config};
use Atcipher\Runware\WebSocket\WebSocketClient;
use Atcipher\Runware\Support\Uuid;

$ws = new WebSocketClient(new Config($_ENV['RUNWARE_API_KEY']));

// Authenticate internally, then send a task
foreach ($ws->send([
    [
        'taskType'       => 'imageInference',
        'taskUUID'       => Uuid::v4(),
        'positivePrompt' => 'a cat',
        'width'          => 512,
        'height'         => 512,
        'model'          => 'civitai:102438@133677',
        'numberResults'  => 1,
    ]
]) as $frame) {
    // Each $frame is the decoded server message (array)
    // Inspect $frame['data'] for results.
}

// Keep-alive (avoid 120s idle close)
$pong = $ws->ping();

Notes

• Auth: Either add Authorization: Bearer <API_KEY> or include an initial authentication task in the array payload (REST). For WebSockets, the first message must be authentication.
• Endpoint: REST base is https://api.runware.ai/v1 (POST a JSON array of tasks). WS is wss://ws-api.runware.ai/v1.
• Responses: Successful calls return { "data": [...] } most of the time; some utilities return { "data": { ... } }. Errors return { "errors": [...] } or { "error": { ... } }. The SDK normalizes nothing on purpose; you get the raw body.
• UUIDs: Always include a unique taskUUID per task. The helpers do this for you.
• Output: Pick outputType = URL (default), dataURI, or base64Data in imageInference tasks.
• Async: Add "deliveryMethod":"async" to your task, then poll with getResponse.
• WS resume: The server returns connectionSessionUUID after auth; reuse it when reconnecting.

Official docs used while building this SDK:

• How to connect & authenticate (REST & WS)
• Task Responses (getResponse)
• Image Upload
• Model Search
• Image Inference (params for text→image / image→image / inpaint / outpaint)

License

MIT © Atcipher Ltd