README

A framework-agnostic PHP client for the Replicate API built on Saloon v4.

Full coverage of the Replicate HTTP API: predictions, models, deployments, trainings, files, collections, hardware, webhooks, and account.

This package is a fork of benbjurstrom/replicate-php which only covered predictions. This version has been entirely rewritten with full API coverage, Saloon v4, PHP 8.2+, and typed DTOs for every endpoint.

Requirements

PHP 8.2+

Installation

composer require marceloeatworld/replicate-php

Quick Start

use MarceloEatWorld\Replicate\Replicate;

$replicate = new Replicate(
    apiToken: $_ENV['REPLICATE_API_TOKEN'],
);

Create a prediction

$prediction = $replicate->predictions()->create(
    version: 'stability-ai/sdxl:c221b2b8ef527988fb59bf24a8b97c4561f1c671f73bd389f866bfb27c061316',
    input: ['prompt' => 'a photo of an astronaut riding a horse on mars'],
);

$prediction->id;     // "xyz123"
$prediction->status; // "starting"

Create a prediction using an official model

$prediction = $replicate->models()->createPrediction(
    owner: 'meta',
    name: 'meta-llama-3-70b-instruct',
    input: ['prompt' => 'Write a haiku about PHP'],
);

Synchronous predictions (wait for result)

$prediction = $replicate->predictions()->create(
    version: 'stability-ai/sdxl:c221b2b8ef527988fb59bf24a8b97c4561f1c671f73bd389f866bfb27c061316',
    input: ['prompt' => 'a painting of a cat'],
    wait: 60, // wait up to 60 seconds for completion
);

if ($prediction->status === 'succeeded') {
    $prediction->output; // result is ready
}

Get prediction status

$prediction = $replicate->predictions()->get('xyz123');
$prediction->status; // "succeeded"
$prediction->output; // ["https://replicate.delivery/..."]

List predictions

$list = $replicate->predictions()->list();
$list->results; // array of PredictionData
$list->next;    // cursor for next page

// Paginate
$nextPage = $replicate->predictions()->list(cursor: $list->next);

Cancel a prediction

$replicate->predictions()->cancel('xyz123');

Webhooks

Pass webhook parameters directly to creation methods:

$prediction = $replicate->predictions()->create(
    version: 'owner/model:version',
    input: ['prompt' => 'hello'],
    webhook: 'https://example.com/webhook',
    webhookEventsFilter: ['completed'],
);

Get the webhook signing secret for verification:

$secret = $replicate->webhooks()->getSecret();
$secret->key; // "whsec_..."

Streaming

$prediction = $replicate->predictions()->create(
    version: 'owner/model:version',
    input: ['prompt' => 'hello'],
    stream: true,
);

// If the model supports streaming, use the stream URL
$prediction->urls['stream']; // SSE endpoint URL

Models

// List public models
$models = $replicate->models()->list();

// Get a model
$model = $replicate->models()->get('stability-ai', 'sdxl');

// Create a model
$model = $replicate->models()->create(
    owner: 'your-username',
    name: 'my-model',
    hardware: 'gpu-a40-large',
    visibility: 'private',
);

// Update a model
$model = $replicate->models()->update('your-username', 'my-model', [
    'description' => 'Updated description',
]);

// Delete a model (must be private, no versions)
$replicate->models()->delete('your-username', 'my-model');

Model Versions

$versions = $replicate->models()->listVersions('stability-ai', 'sdxl');
$version = $replicate->models()->getVersion('stability-ai', 'sdxl', 'abc123');
$replicate->models()->deleteVersion('your-username', 'my-model', 'abc123');

Deployments

// List deployments
$deployments = $replicate->deployments()->list();

// Get a deployment
$deployment = $replicate->deployments()->get('your-username', 'my-deployment');

// Create a deployment
$deployment = $replicate->deployments()->create(
    name: 'my-deployment',
    model: 'your-username/my-model',
    version: 'abc123...',
    hardware: 'gpu-a40-large',
    minInstances: 1,
    maxInstances: 3,
);

// Update a deployment
$deployment = $replicate->deployments()->update('your-username', 'my-deployment', [
    'min_instances' => 2,
    'max_instances' => 5,
]);

// Create prediction on a deployment
$prediction = $replicate->deployments()->createPrediction(
    owner: 'your-username',
    name: 'my-deployment',
    input: ['prompt' => 'hello world'],
);

// Delete a deployment
$replicate->deployments()->delete('your-username', 'my-deployment');

Trainings

// Create a training
$training = $replicate->trainings()->create(
    owner: 'stability-ai',
    name: 'sdxl',
    versionId: 'abc123...',
    destination: 'your-username/my-trained-model',
    input: ['train_data' => 'https://example.com/data.zip'],
    webhook: 'https://example.com/training-done',
);

// Get training status
$training = $replicate->trainings()->get($training->id);

// List trainings
$trainings = $replicate->trainings()->list();

// Cancel a training
$replicate->trainings()->cancel($training->id);

Files

// Upload a file
$file = $replicate->files()->upload(
    content: file_get_contents('/path/to/image.jpg'),
    filename: 'image.jpg',
    contentType: 'image/jpeg',
);

// Get file metadata
$file = $replicate->files()->get($file->id);

// List files
$files = $replicate->files()->list();

// Delete a file
$replicate->files()->delete($file->id);

Collections

// List collections
$collections = $replicate->collections()->list();

// Get a collection with its models
$collection = $replicate->collections()->get('text-to-image');
$collection->models; // array of ModelData

Hardware

// List available hardware
$hardware = $replicate->hardware()->list();
// Returns array of HardwareData with name and sku

Account

$account = $replicate->account()->get();
$account->username;
$account->type; // "user" or "organization"

Using with Laravel

Add your credentials to your services config:

// config/services.php
'replicate' => [
    'api_token' => env('REPLICATE_API_TOKEN'),
],

Bind in a service provider:

// app/Providers/AppServiceProvider.php
public function register(): void
{
    $this->app->bind(Replicate::class, fn () => new Replicate(
        apiToken: config('services.replicate.api_token'),
    ));
}

Use anywhere:

$prediction = app(Replicate::class)->predictions()->get($id);

Testing

Use Saloon's built-in mocking:

use Saloon\Http\Faking\MockClient;
use Saloon\Http\Faking\MockResponse;
use MarceloEatWorld\Replicate\Requests\Predictions\GetPrediction;

$mockClient = new MockClient([
    GetPrediction::class => MockResponse::make(['id' => 'xyz', 'status' => 'succeeded']),
]);

$replicate = new Replicate('test-token');
$replicate->withMockClient($mockClient);

$prediction = $replicate->predictions()->get('xyz');
$prediction->status; // "succeeded"

Response Data

All responses are returned as typed data objects:

DTO	Description
`AccountData`	Account info
`PredictionData`	Single prediction
`PredictionsData`	Paginated prediction list
`ModelData`	Single model
`ModelsData`	Paginated model list
`ModelVersionData`	Single model version
`ModelVersionsData`	Paginated version list
`CollectionData`	Single collection with models
`CollectionsData`	Paginated collection list
`DeploymentData`	Single deployment
`DeploymentsData`	Paginated deployment list
`TrainingData`	Single training
`TrainingsData`	Paginated training list
`FileData`	Single file metadata
`FilesData`	Paginated file list
`HardwareData`	Hardware option (name + SKU)
`WebhookSecretData`	Webhook signing secret

Credits

Marcelo Pereira
Originally forked from benbjurstrom/replicate-php

License

The MIT License (MIT). See License File for more information.

marceloeatworld / replicate-php

Maintainers

Package info

Statistics

Security