PHPackages                             aimatchfun/php-runware-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. aimatchfun/php-runware-sdk

ActiveLibrary[Image & Media](/categories/media)

aimatchfun/php-runware-sdk
==========================

PHP SDK for Runware AI - Powerful image generation and manipulation

4.0.0(2mo ago)1292↓50%1MITPHPPHP ^8.4CI failing

Since Jul 23Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/aimatchfun/php-runware-sdk)[ Packagist](https://packagist.org/packages/aimatchfun/php-runware-sdk)[ Docs](https://github.com/aimatchfun/php-runware-sdk)[ RSS](/packages/aimatchfun-php-runware-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (4)Versions (24)Used By (1)

PHP Runware
===========

[](#php-runware)

A PHP wrapper for the Runware AI API, allowing simple and efficient AI image generation.

📑 Navigation
------------

[](#-navigation)

- [Installation](#installation)
- [Basic Usage](#basic-usage)
    - [Text to Image](#text-to-image)
    - [Inpainting](#inpainting)
    - [Image Upload](#image-upload)
- [Examples](#examples)
    - [Image Upload Examples](#image-upload-examples)
    - [Inpainting Examples](#inpainting-examples)
    - [Text to Image Generation](#text-to-image-generation-with-different-models)
    - [Output Types and Formats](#output-types-and-formats)
    - [Using Different Schedulers](#using-different-schedulers)
    - [Advanced Configuration](#advanced-configuration)
    - [Using LoRA Models](#using-lora-models)
    - [Using Custom Models](#using-custom-models)
    - [Uploading LoRA Models](#uploading-lora-models)
    - [Uploading Custom Models](#uploading-custom-models)
    - [Error Handling](#error-handling)
    - [Parameter Validation](#parameter-validation)
- [Documentation](#documentation)
- [License](#license)

---

Installation
------------

[](#installation)

```
composer require aimatchfun/php-runware-sdk
```

Response Format
---------------

[](#response-format)

All service methods (`run()` and `runAsync()`) return a `RunwareResponse` object that contains structured data from the API. The `RunwareResponse` class provides convenient methods to access the results:

```
use AiMatchFun\PhpRunwareSDK\RunwareResponse;
use AiMatchFun\PhpRunwareSDK\RunwareImageResponse;

$result = $imageInference
    ->positivePrompt('A beautiful sunset')
    ->run();

// $result is a RunwareResponse instance
$firstImage = $result->first(); // Get the first RunwareImageResponse
$imageURL = $result->first()?->imageURL; // Access image URL directly
$allImages = $result->all(); // Get all images as array
$count = $result->count(); // Get number of results

// Or use helper method to get image data by output type
$imageURL = $result->getImageData('URL'); // Get URL, base64Data, or dataURI
```

**Important:** The `ImageUpload` service is an exception - its `run()` method returns a `string` (the image UUID) instead of `RunwareResponse`, as it's designed to return just the UUID for use in other operations.

Basic Usage
-----------

[](#basic-usage)

### Text to Image

[](#text-to-image)

```
use AiMatchFun\PhpRunwareSDK\ImageInference;
use AiMatchFun\PhpRunwareSDK\OutputType;
use AiMatchFun\PhpRunwareSDK\OutputFormat;
use AiMatchFun\PhpRunwareSDK\Scheduler;
use AiMatchFun\PhpRunwareSDK\RunwareModel;
use AiMatchFun\PhpRunwareSDK\PromptWeighting;

$imageInference = new ImageInference('your_api_key');

$result = $imageInference
    ->positivePrompt('A beautiful sunset over a calm ocean')
    ->height(768)
    ->width(1024)
    ->model(RunwareModel::REAL_DREAM_SDXL_PONY_14)
    ->steps(30)
    ->cfgScale(8.5)
    ->numberResults(1)
    ->outputType(OutputType::URL)
    ->outputFormat(OutputFormat::PNG)
    ->negativePrompt('low quality, blurred')
    ->run();

// $result is a RunwareResponse instance
$imageURL = $result->first()?->imageURL; // Get the image URL
// Or use helper method:
$imageURL = $result->getImageData('URL');
```

**Note:** The `negativePrompt()` method is optional. You can generate images without specifying a negative prompt:

```
$result = $imageInference
    ->positivePrompt('A beautiful sunset over a calm ocean')
    ->height(768)
    ->width(1024)
    ->model(RunwareModel::REAL_DREAM_SDXL_PONY_14)
    ->steps(30)
    ->cfgScale(8.5)
    ->numberResults(1)
    ->outputType(OutputType::URL)
    ->outputFormat(OutputFormat::PNG)
    ->run();

// $result is a RunwareResponse instance
$imageURL = $result->first()?->imageURL;
```

### Inpainting

[](#inpainting)

Inpainting allows you to selectively edit specific areas of an image by providing a seed image and a mask image:

```
use AiMatchFun\PhpRunwareSDK\Inpainting;
use AiMatchFun\PhpRunwareSDK\OutputType;
use AiMatchFun\PhpRunwareSDK\RunwareModel;

$inpainting = new Inpainting('your_api_key');

$result = $inpainting
    ->seedImage('59a2edc2-45e6-429f-be5f-7ded59b92046') // Image UUID or URL
    ->maskImage('5988e195-8100-4b91-b07c-c7096d0861aa') // Mask UUID or URL
    ->positivePrompt('a serene beach at sunset')
    ->negativePrompt('blur, distortion')
    ->strength(0.8) // Strength of the inpainting effect (0.0 to 1.0)
    ->maskMargin(64) // Extra context pixels around masked region (32-128)
    ->model(RunwareModel::REAL_DREAM_SDXL_PONY_14)
    ->width(1024)
    ->height(1024)
    ->outputType(OutputType::URL)
    ->run();

// $result is a RunwareResponse instance
$inpaintedImageURL = $result->first()?->imageURL;
```

**Inpainting Parameters:**

- `seedImage(string $image)`: The original image you wish to edit (UUID, URL, base64, or data URI)
- `maskImage(string $image)`: Defines the area to be modified (UUID, URL, base64, or data URI)
    - White areas (255,255,255) indicate regions to be modified
    - Black areas (0,0,0) indicate regions to preserve
    - Gray values create partial modification
- `strength(float $strength)`: Strength of the inpainting effect (0.0 to 1.0, default: 0.8)
- `maskMargin(int $margin)`: Adds extra context pixels around masked region (32-128 pixels)

For more details about inpainting, see the [Runware Inpainting Documentation](https://runware.ai/docs/en/image-inference/inpainting).

### Image Upload

[](#image-upload)

Image Upload allows you to upload images to the Runware API and receive an image UUID that can be used in other operations like inpainting. The SDK provides two methods for uploading images:

**Upload from Local File Path:**

```
use AiMatchFun\PhpRunwareSDK\ImageUpload;

$imageUpload = new ImageUpload('your_api_key');

// Upload from a local file path (automatically converts to base64)
$imageUUID = $imageUpload
    ->uploadFromLocalPath('/path/to/image.jpg')
    ->run();

// The returned UUID can be used in other operations
echo "Image uploaded with UUID: " . $imageUUID;
```

**Upload from URL:**

```
use AiMatchFun\PhpRunwareSDK\ImageUpload;

$imageUpload = new ImageUpload('your_api_key');

// Upload from a public URL
$imageUUID = $imageUpload
    ->uploadFromURL('https://example.com/image.png')
    ->run();

// The returned UUID can be used in other operations
echo "Image uploaded with UUID: " . $imageUUID;
```

**Image Upload Methods:**

- `uploadFromLocalPath(string $path)`: Upload an image from a local file path. The file is automatically converted to base64 format.
- `uploadFromURL(string $url)`: Upload an image from a public URL.
- `image(string $image)`: Upload an image from URL, base64 string, or data URI. Automatically detects the format:
    - If starts with "http://" or "https://", treats as URL
    - If starts with "data:", treats as data URI and extracts base64
    - Otherwise, treats as base64 string

**Example using image() method:**

```
use AiMatchFun\PhpRunwareSDK\ImageUpload;

$imageUpload = new ImageUpload('your_api_key');

// Upload from URL
$imageUUID = $imageUpload
    ->image('https://example.com/image.png')
    ->run();

// Upload from base64 string
$base64Image = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
$imageUUID = $imageUpload
    ->image($base64Image)
    ->run();

// Upload from data URI
$dataURI = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
$imageUUID = $imageUpload
    ->image($dataURI)
    ->run();
```

For more details about image upload, see the [Runware Image Upload Documentation](https://runware.ai/docs/en/utilities/image-upload).

Examples
--------

[](#examples)

### Image Upload Examples

[](#image-upload-examples)

#### Uploading from URL

[](#uploading-from-url)

```
use AiMatchFun\PhpRunwareSDK\ImageUpload;

$imageUpload = new ImageUpload('your_api_key');

$imageUUID = $imageUpload
    ->uploadFromURL('https://example.com/my-image.png')
    ->run();

echo "Image UUID: " . $imageUUID;
```

#### Uploading from Local File Path

[](#uploading-from-local-file-path)

```
use AiMatchFun\PhpRunwareSDK\ImageUpload;

$imageUpload = new ImageUpload('your_api_key');

// Upload from a local file path (automatically converts to base64)
$imageUUID = $imageUpload
    ->uploadFromLocalPath('/path/to/image.jpg')
    ->run();

echo "Image UUID: " . $imageUUID;
```

#### Using Uploaded Image with Inpainting

[](#using-uploaded-image-with-inpainting)

```
use AiMatchFun\PhpRunwareSDK\ImageUpload;
use AiMatchFun\PhpRunwareSDK\Inpainting;
use AiMatchFun\PhpRunwareSDK\RunwareModel;
use AiMatchFun\PhpRunwareSDK\OutputType;

// Step 1: Upload the image
$imageUpload = new ImageUpload('your_api_key');
$imageUUID = $imageUpload
    ->uploadFromURL('https://example.com/image.png')
    ->run();

// Step 2: Upload the mask image
$maskUUID = $imageUpload
    ->uploadFromURL('https://example.com/mask.png')
    ->run();

// Step 3: Use the uploaded images in inpainting
$inpainting = new Inpainting('your_api_key');
$result = $inpainting
    ->seedImage($imageUUID)      // Use the uploaded image UUID
    ->maskImage($maskUUID)        // Use the uploaded mask UUID
    ->positivePrompt('a beautiful blue sky')
    ->negativePrompt('blur, distortion')
    ->strength(0.8)
    ->model(RunwareModel::REAL_DREAM_SDXL_PONY_14)
    ->outputType(OutputType::URL)
        ->run();

// $result is a RunwareResponse instance
echo "Inpainted image: " . $result->first()?->imageURL;
```

### Inpainting Examples

[](#inpainting-examples)

#### Basic Inpainting

[](#basic-inpainting)

```
use AiMatchFun\PhpRunwareSDK\Inpainting;
use AiMatchFun\PhpRunwareSDK\OutputType;
use AiMatchFun\PhpRunwareSDK\RunwareModel;

$inpainting = new Inpainting('your_api_key');

// Simple object removal
$result = $inpainting
    ->seedImage('image-uuid-or-url')
    ->maskImage('mask-uuid-or-url')
    ->positivePrompt('white wall')
    ->negativePrompt('blur, distortion')
    ->strength(0.8)
    ->model(RunwareModel::REAL_DREAM_SDXL_PONY_14)
    ->outputType(OutputType::URL)
    ->run();
```

#### Inpainting with Mask Margin for Enhanced Detail

[](#inpainting-with-mask-margin-for-enhanced-detail)

```
// Using maskMargin to enhance facial features
$result = $inpainting
    ->seedImage('image-uuid')
    ->maskImage('face-mask-uuid')
    ->positivePrompt('a detailed face with natural lighting')
    ->maskMargin(64) // Enhances detail by zooming into masked area
    ->strength(0.8)
    ->steps(40) // Higher steps for better detail
    ->cfgScale(8.0)
    ->run();
```

#### Inpainting with Different Strength Values

[](#inpainting-with-different-strength-values)

```
// Low strength - subtle modification
$result = $inpainting
    ->seedImage('image-uuid')
    ->maskImage('mask-uuid')
    ->positivePrompt('red apple')
    ->strength(0.5) // More influence from original image
    ->run();

// High strength - complete replacement
$result = $inpainting
    ->seedImage('image-uuid')
    ->maskImage('mask-uuid')
    ->positivePrompt('blue sky with clouds')
    ->strength(0.9) // More creative deviation
    ->run();
```

### Text to Image Generation with Different Models

[](#text-to-image-generation-with-different-models)

```
use AiMatchFun\PhpRunwareSDK\ImageInference;
use AiMatchFun\PhpRunwareSDK\RunwareModel;

$imageInference = new ImageInference('your_api_key');

// Using Pony Realism model
$result = $imageInference
    ->positivePrompt('A serene mountain landscape at sunset')
    ->model(RunwareModel::PONY_REALISM)
    ->run();

// Using Goddess of Realism model
$result = $imageInference
    ->positivePrompt('A portrait of a young woman')
    ->model(RunwareModel::GODDESS_OF_REALISM)
    ->run();
```

### Output Types and Formats

[](#output-types-and-formats)

```
use AiMatchFun\PhpRunwareSDK\OutputType;
use AiMatchFun\PhpRunwareSDK\OutputFormat;

// Get result as URL
$result = $imageInference
    ->positivePrompt('A cyberpunk city at night')
    ->outputType(OutputType::URL)
    ->outputFormat(OutputFormat::PNG)
    ->run();
$imageURL = $result->getImageData('URL'); // Get URL from RunwareResponse

// Get result as base64 data
$result = $imageInference
    ->positivePrompt('An abstract painting')
    ->outputType(OutputType::BASE64_DATA)
    ->outputFormat(OutputFormat::JPG)
    ->run();
$base64Data = $result->getImageData('base64Data'); // Get base64 from RunwareResponse

// Get result as data URI
$result = $imageInference
    ->positivePrompt('A fantasy landscape')
    ->outputType(OutputType::DATA_URI)
    ->outputFormat(OutputFormat::WEBP)
    ->run();
$dataURI = $result->getImageData('dataURI'); // Get data URI from RunwareResponse
```

### Using Different Schedulers

[](#using-different-schedulers)

```
use AiMatchFun\PhpRunwareSDK\Scheduler;

// Using DPM++ 2M scheduler
$result = $imageInference
    ->positivePrompt('A beautiful landscape')
    ->scheduler(Scheduler::DPM_PLUS_PLUS_2M)
    ->run();

// Using Euler scheduler
$result = $imageInference
    ->positivePrompt('A sci-fi scene')
    ->scheduler(Scheduler::EULER)
    ->run();

// Using Karras scheduler
$result = $imageInference
    ->positivePrompt('An artistic portrait')
    ->scheduler(Scheduler::DPM_PLUS_PLUS_KARRAS)
    ->run();
```

### Advanced Configuration

[](#advanced-configuration)

```
use AiMatchFun\PhpRunwareSDK\PromptWeighting;

// Using advanced settings with prompt weighting
$result = $imageInference
    ->positivePrompt('A magical forest scene')
    ->negativePrompt('blurry, low quality, distorted')
    ->height(1024)
    ->width(1024)
    ->steps(30)
    ->cfgScale(7.5)
    ->numberResults(4)
    ->outputType(OutputType::URL)
    ->outputFormat(OutputFormat::PNG)
    ->model(RunwareModel::REAL_DREAM_SDXL_PONY_14)
    ->promptWeighting(PromptWeighting::COMPEL)
    ->run();

// Using acceleration features
$result = $imageInference
    ->positivePrompt('A fantasy landscape')
    ->teaCache(true)
    ->teaCacheDistance(0.5)
    ->deepCache(true)
    ->deepCacheInterval(3)
    ->run();
```

### Using LoRA Models

[](#using-lora-models)

```
// Using multiple LoRA models with different weights
$result = $imageInference
    ->positivePrompt('A beautiful portrait')
    ->addLora('civitai:927305@1037996', 1.0)  // First LoRA with weight 1.0
    ->addLora('civitai:368139@411375', 0.8)   // Second LoRA with weight 0.8
    ->addLora('civitai:888213@486749', 0.5)   // Third LoRA with weight 0.5
    ->run();

// Using a single LoRA model
$result = $imageInference
    ->positivePrompt('A fantasy character')
    ->addLora('civitai:927305@1037996', 0.7)  // Using LoRA with weight 0.7
    ->run();
```

### Using Custom Models

[](#using-custom-models)

```
use AiMatchFun\PhpRunwareSDK\RunwareModel;

// Using a specific model version with ENUM
$result = $imageInference
    ->positivePrompt('A beautiful landscape')
    ->model(RunwareModel::REAL_DREAM_SDXL_PONY_14)
    ->run();

// Using different model variants with ENUM
$result = $imageInference
    ->positivePrompt('A portrait photo')
    ->model(RunwareModel::REAL_DREAM_SDXL_PONY_11)
    ->run();

// Using model with string directly (AIR format)
$result = $imageInference
    ->positivePrompt('A fantasy scene')
    ->model('civitai:618692@691639') // Direct AIR string
    ->run();
```

**Note:** The `model()` method accepts both `RunwareModel` enum values and string values (AIR format). This allows you to use predefined models from the enum or specify custom models using their AIR identifier directly.

### Uploading LoRA Models

[](#uploading-lora-models)

```
use AiMatchFun\PhpRunwareSDK\UploadLora;
use Ramsey\Uuid\Uuid;

$uploader = new UploadLora('your_api_key');

$result = $uploader->upload([
    'air' => 'air-of-your-model',
    'uniqueIdentifier' => Uuid::uuid4()->toString(),
    'name' => 'name-of-your-model',
    'version' => '1.0',
    'downloadURL' => 'public-url-to-your-model',
    'tags' => ['character', 'anime', 'artstyle'],
    'positiveTriggerWords' => 'positive-trigger-words',
    'shortDescription' => 'short-description-of-your-model',
    'comment' => 'comment-of-your-model'
]);
```

### Uploading Custom Models

[](#uploading-custom-models)

```
use AiMatchFun\PhpRunwareSDK\UploadModel;
use Ramsey\Uuid\Uuid;

$uploader = new UploadModel('your_api_key');

$result = $uploader->upload([
    'air' => 'air-of-your-model',
    'uniqueIdentifier' => Uuid::uuid4()->toString(),
    'name' => 'name-of-your-model',
    'version' => '1.0',
    'downloadURL' => 'public-url-to-your-model',
    'tags' => ['character', 'anime', 'artstyle'],
    'positiveTriggerWords' => 'positive-trigger-words',
    'shortDescription' => 'short-description-of-your-model',
    'comment' => 'comment-of-your-model'
]);
```

The upload methods accept the following parameters:

- `air`: Unique identifier for your model in the Runware system
- `uniqueIdentifier`: A UUID v4 string to identify your upload
- `name`: Name of your model
- `version`: Version string of your model
- `downloadURL`: Public URL where the model can be downloaded
- `tags`: Array of relevant tags for categorizing the model
- `positiveTriggerWords`: Keywords that activate or work well with the model
- `shortDescription`: Brief description of what the model does
- `comment`: Additional notes or comments about the model

### Error Handling

[](#error-handling)

```
use Exception;

try {
    $result = $imageInference
        ->positivePrompt('A beautiful landscape')
        ->run();
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}
```

### Parameter Validation

[](#parameter-validation)

The SDK includes built-in validation for all parameters:

**ImageInference:**

- Height and width must be between 128 and 2048 and divisible by 64
- Steps must be between 1 and 100
- CFG Scale must be between 0 and 30
- Number of results must be between 1 and 20
- CLIP skip must be between 0 and 2
- TeaCache distance must be between 0 and 1

**Inpainting:**

- Height and width must be between 128 and 2048 and divisible by 64
- Steps must be between 1 and 100
- CFG Scale must be between 0 and 30
- Number of results must be between 1 and 20
- CLIP skip must be between 0 and 2
- Strength must be between 0.0 and 1.0
- Mask margin must be between 32 and 128
- Seed image and mask image are required

**Image Upload:**

- `uploadFromLocalPath()`: Path cannot be empty, file must exist and be readable
- `uploadFromURL()`: URL cannot be empty
- Local files are automatically converted to base64 format

Documentation
-------------

[](#documentation)

For more detailed information on the API, please refer to the [Runware API Documentation](https://runware.ai/docs).

License
-------

[](#license)

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

###  Health Score

48

—

FairBetter than 94% of packages

Maintenance85

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 76.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~10 days

Total

23

Last Release

80d ago

Major Versions

v1.1.0 → 2.0.02025-12-08

2.10.0 → v3.0.02026-01-17

v3.0.1 → 4.0.02026-02-27

PHP version history (2 changes)v1.0.0PHP ^8.0

2.0.0PHP ^8.4

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/209401277?v=4)[AIMatch Fun](/maintainers/aimatchfun)[@aimatchfun](https://github.com/aimatchfun)

---

Top Contributors

[![aimatchfun](https://avatars.githubusercontent.com/u/209401277?v=4)](https://github.com/aimatchfun "aimatchfun (40 commits)")[![diegolist](https://avatars.githubusercontent.com/u/110676997?v=4)](https://github.com/diegolist "diegolist (11 commits)")[![daavelar](https://avatars.githubusercontent.com/u/7144672?v=4)](https://github.com/daavelar "daavelar (1 commits)")

---

Tags

phpsdkaiartificial intelligenceimage-generationrunware

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/aimatchfun-php-runware-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/aimatchfun-php-runware-sdk/health.svg)](https://phpackages.com/packages/aimatchfun-php-runware-sdk)
```

###  Alternatives

[opentok/opentok

OpenTok is a platform for creating real time streaming video applications, created by TokBox.

1413.0M10](/packages/opentok-opentok)[softcreatr/php-mistral-ai-sdk

A powerful and easy-to-use PHP SDK for the Mistral AI API, allowing seamless integration of advanced AI-powered features into your PHP projects.

1517.9k](/packages/softcreatr-php-mistral-ai-sdk)[softcreatr/php-perplexity-ai-sdk

A powerful and easy-to-use PHP SDK for the pplx (Perplexity) API, allowing seamless integration of advanced AI-powered features into your PHP projects..

149.1k](/packages/softcreatr-php-perplexity-ai-sdk)[batdan/midjourney-api-php

Generate images Midjourney (Discord API). URLs in prompt accepted

222.2k](/packages/batdan-midjourney-api-php)[marceloeatworld/falai-php

Professional PHP client for the fal.ai serverless AI platform

105.5k](/packages/marceloeatworld-falai-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)