OpenAI PHP SDK: Complete Guide with Code Examples (2026)

composer require openai-php/client

<?php

require 'vendor/autoload.php';

$client = OpenAI::client(getenv('OPENAI_API_KEY'));

export OPENAI_API_KEY=sk-proj-...

$response = $client->chat()->create([
    'model' => 'gpt-4o-mini',
    'messages' => [
        ['role' => 'system', 'content' => 'You are a helpful assistant.'],
        ['role' => 'user',   'content' => 'What is the capital of France?'],
    ],
]);

echo $response->choices[0]->message->content;
// Paris

$messages = [
    ['role' => 'system', 'content' => 'You are a helpful assistant.'],
];

function chat(array &$messages, string $input, $client): string
{
    $messages[] = ['role' => 'user', 'content' => $input];

    $response = $client->chat()->create([
        'model' => 'gpt-4o-mini',
        'messages' => $messages,
    ]);

    $reply = $response->choices[0]->message->content;
    $messages[] = ['role' => 'assistant', 'content' => $reply];

    return $reply;
}

echo chat($messages, 'My name is Alex.', $client);  // Nice to meet you, Alex!
echo chat($messages, 'What is my name?', $client);  // Your name is Alex.

$stream = $client->chat()->createStreamed([
    'model' => 'gpt-4o-mini',
    'messages' => [
        ['role' => 'user', 'content' => 'Write a short poem about PHP.'],
    ],
]);

foreach ($stream as $response) {
    $delta = $response->choices[0]->delta->content;
    if ($delta !== null) {
        echo $delta;
        ob_flush();
        flush();
    }
}

$response = $client->chat()->create([
    'model' => 'gpt-4o-mini',
    'messages' => [
        ['role' => 'user', 'content' => "What's the weather in Kyiv?"],
    ],
    'tools' => [
        [
            'type' => 'function',
            'function' => [
                'name' => 'get_weather',
                'description' => 'Get current weather for a city',
                'parameters' => [
                    'type' => 'object',
                    'properties' => [
                        'city' => ['type' => 'string', 'description' => 'City name'],
                    ],
                    'required' => ['city'],
                ],
            ],
        ],
    ],
    'tool_choice' => 'auto',
]);

$message = $response->choices[0]->message;

if ($message->toolCalls) {
    foreach ($message->toolCalls as $toolCall) {
        $name = $toolCall->function->name;
        $args = json_decode($toolCall->function->arguments, true);
        // Execute your function here: call_weather_api($args['city'])
        echo "Model wants to call: $name with args: " . json_encode($args);
    }
}

$response = $client->embeddings()->create([
    'model' => 'text-embedding-3-small',
    'input' => 'Laravel is a PHP framework for web artisans.',
]);

$vector = $response->embeddings[0]->embedding;
// 1536-dimensional float array

// Batch embeddings
$response = $client->embeddings()->create([
    'model' => 'text-embedding-3-small',
    'input' => ['First text', 'Second text', 'Third text'],
]);

foreach ($response->embeddings as $embedding) {
    // $embedding->embedding — vector
    // $embedding->index    — position in input array
}

// Generate image
$response = $client->images()->create([
    'model'   => 'dall-e-3',
    'prompt'  => 'A futuristic PHP elephant mascot',
    'n'       => 1,
    'size'    => '1024x1024',
    'quality' => 'standard',
]);

$imageUrl = $response->data[0]->url;
echo $imageUrl; // https://oaidalleapiprodscus.blob.core.windows.net/...

// Edit an existing image (requires mask)
$response = $client->images()->edit([
    'image'  => fopen('original.png', 'r'),
    'mask'   => fopen('mask.png', 'r'),
    'prompt' => 'Add a rainbow in the background',
    'n'      => 1,
    'size'   => '1024x1024',
]);

$response = $client->audio()->transcribe([
    'model' => 'whisper-1',
    'file'  => fopen('audio.mp3', 'r'),
]);

echo $response->text;
// The transcribed text from the audio file

// Translate non-English audio to English
$response = $client->audio()->translate([
    'model' => 'whisper-1',
    'file'  => fopen('french_audio.mp3', 'r'),
]);

$response = $client->moderations()->create([
    'input' => $userMessage,
]);

$result = $response->results[0];

if ($result->flagged) {
    $categories = array_filter((array) $result->categories);
    echo "Flagged categories: " . implode(', ', array_keys($categories));
} else {
    echo "Content is safe";
}

use OpenAI\Exceptions\ErrorException;
use OpenAI\Exceptions\TransporterException;
use OpenAI\Exceptions\UnserializableResponse;

try {
    $response = $client->chat()->create([
        'model'    => 'gpt-4o-mini',
        'messages' => [['role' => 'user', 'content' => $input]],
    ]);
    return $response->choices[0]->message->content;

} catch (ErrorException $e) {
    // 400 Bad Request, 401 Unauthorized, 429 Rate Limit, 500 Server Error
    $code = $e->getCode();
    if ($code === 429) {
        // Rate limited — implement exponential backoff
        sleep(2);
        // retry...
    }
    throw new RuntimeException("OpenAI error [{$code}]: " . $e->getMessage());

} catch (TransporterException $e) {
    // Network timeout, DNS failure, etc.
    throw new RuntimeException("Network error: " . $e->getMessage());

} catch (UnserializableResponse $e) {
    // Unexpected response format
    throw new RuntimeException("Invalid response: " . $e->getMessage());
}

$client = OpenAI::factory()
    ->withApiKey(getenv('OPENAI_API_KEY'))
    ->withOrganization('org-...')       // optional
    ->withBaseUri('https://api.openai.com/v1')
    ->withHttpClient(new \GuzzleHttp\Client(['timeout' => 30]))
    ->withHttpHeader('X-Custom-Header', 'value')
    ->make();

$models = $client->models()->list();

foreach ($models->data as $model) {
    echo $model->id . "\n";
}
// gpt-4o, gpt-4o-mini, gpt-3.5-turbo, text-embedding-3-small, ...

// Get a single model
$model = $client->models()->retrieve('gpt-4o-mini');
echo $model->ownedBy; // openai