Add image streaming support

README.md

@@ -1293,6 +1293,24 @@ foreach ($response->data as $data) {
 $response->toArray(); // ['created' => 1589478378, data => ['url' => 'https://oaidalleapiprodscus...', ...]]
 ```
 
+#### `create streamed`
+
+When you create an image with stream set to true, the server will emit server-sent events to the client as the image is generated. All events and their payloads can be found in [OpenAI docs](https://platform.openai.com/docs/api-reference/images-streaming).
+
+```php
+$stream = $client->images()->createStreamed([
+    'model' => 'gpt-image-1',
+    'prompt' => 'A cute baby sea otter',
+    'n' => 1,
+    'size' => '1024x1024',
+    'response_format' => 'url',
+]);
+
+foreach ($stream as $image) {
+    $image->type; // 'image_generation.partial_image'
+}
+```
+
 #### `edit`
 
 Creates an edited or extended image given an original image and a prompt.
@@ -1317,6 +1335,24 @@ foreach ($response->data as $data) {
 $response->toArray(); // ['created' => 1589478378, data => ['url' => 'https://oaidalleapiprodscus...', ...]]
 ```
 
+#### `edit streamed`
+
+When you edit an image with stream set to true, the server will emit server-sent events to the client as the image is generated. All events and their payloads can be found in [OpenAI docs](https://platform.openai.com/docs/api-reference/images-streaming).
+
+```php
+$stream = $client->images()->editStreamed([
+    'model' => 'gpt-image-1',
+    'prompt' => 'A cute baby sea otter',
+    'n' => 1,
+    'size' => '1024x1024',
+    'response_format' => 'url',
+]);
+
+foreach ($stream as $image) {
+    $image->type; // 'image_generation.partial_image'
+}
+```
+
 #### `variation`
 
 Creates a variation of a given image.

src/Resources/Images.php

@@ -6,13 +6,17 @@
 
 use OpenAI\Contracts\Resources\ImagesContract;
 use OpenAI\Responses\Images\CreateResponse;
+use OpenAI\Responses\Images\CreateStreamedResponse;
 use OpenAI\Responses\Images\EditResponse;
+use OpenAI\Responses\Images\EditStreamedResponse;
 use OpenAI\Responses\Images\VariationResponse;
+use OpenAI\Responses\StreamResponse;
 use OpenAI\ValueObjects\Transporter\Payload;
 use OpenAI\ValueObjects\Transporter\Response;
 
 final class Images implements ImagesContract
 {
+    use Concerns\Streamable;
     use Concerns\Transportable;
 
     /**
@@ -24,6 +28,8 @@ final class Images implements ImagesContract
      */
     public function create(array $parameters): CreateResponse
     {
+        $this->ensureNotStreamed($parameters);
+
         $payload = Payload::create('images/generations', $parameters);
 
         /** @var Response<array{created: int, data: array<int, array{url?: string, b64_json?: string, revised_prompt?: string}>, usage?: array{total_tokens: int, input_tokens: int, output_tokens: int, input_tokens_details: array{text_tokens: int, image_tokens: int}}}> $response */
@@ -32,6 +38,25 @@ public function create(array $parameters): CreateResponse
         return CreateResponse::from($response->data(), $response->meta());
     }
 
+    /**
+     * Creates a streamed image given a prompt.
+     *
+     * @see https://platform.openai.com/docs/api-reference/images/create
+     *
+     * @param  array<string, mixed>  $parameters
+     * @return StreamResponse<CreateStreamedResponse>
+     */
+    public function createStreamed(array $parameters): StreamResponse
+    {
+        $parameters = $this->setStreamParameter($parameters);
+
+        $payload = Payload::create('images/generations', $parameters);
+
+        $response = $this->transporter->requestStream($payload);
+
+        return new StreamResponse(CreateStreamedResponse::class, $response);
+    }
+
     /**
      * Creates an edited or extended image given an original image and a prompt.
      *
@@ -49,6 +74,24 @@ public function edit(array $parameters): EditResponse
         return EditResponse::from($response->data(), $response->meta());
     }
 
+    /**
+     * Creates a streamed image edit given a prompt.
+     *
+     * @see https://platform.openai.com/docs/api-reference/images/create
+     *
+     * @param  array<string, mixed>  $parameters
+     * @return StreamResponse<EditStreamedResponse>
+     */
+    public function editStreamed(array $parameters): StreamResponse
+    {
+        $parameters = $this->setStreamParameter($parameters, 'true'); // Ensure the parameter is a string for upload
+
+        $payload = Payload::upload('images/edits', $parameters);
+        $response = $this->transporter->requestStream($payload);
+
+        return new StreamResponse(EditStreamedResponse::class, $response);
+    }
+
     /**
      * Creates a variation of a given image.
      *

src/Responses/Images/CreateStreamedResponse.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\Images;
+
+use OpenAI\Contracts\ResponseContract;
+use OpenAI\Exceptions\UnknownEventException;
+use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Responses\Images\Streaming\Error;
+use OpenAI\Responses\Images\Streaming\ImageGenerationCompleted;
+use OpenAI\Responses\Images\Streaming\ImageGenerationPartialImage;
+use OpenAI\Testing\Responses\Concerns\FakeableForStreamedResponse;
+
+/**
+ * @phpstan-type CreateStreamedResponseType array{event: string, data: array<string, mixed>}
+ *
+ * @implements ResponseContract<CreateStreamedResponseType>
+ */
+final class CreateStreamedResponse implements ResponseContract
+{
+    /**
+     * @use ArrayAccessible<CreateStreamedResponseType>
+     */
+    use ArrayAccessible;
+
+    use FakeableForStreamedResponse;
+
+    private function __construct(
+        public readonly string $event,
+        public readonly ImageGenerationPartialImage|ImageGenerationCompleted|Error $response,
+    ) {}
+
+    /**
+     * @param  array<string, mixed>  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        $event = $attributes['type'] ?? throw new UnknownEventException('Missing event type in streamed response');
+        $meta = $attributes['__meta'];
+        unset($attributes['__meta']);
+
+        $response = match ($event) {
+            'image_generation.partial_image' => ImageGenerationPartialImage::from($attributes, $meta), // @phpstan-ignore-line
+            'image_generation.completed' => ImageGenerationCompleted::from($attributes, $meta), // @phpstan-ignore-line
+            'error' => Error::from($attributes, $meta), // @phpstan-ignore-line
+            default => throw new UnknownEventException('Unknown Images streaming event: '.$event),
+        };
+
+        return new self(
+            event: $event, // @phpstan-ignore-line
+            response: $response,
+        );
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function toArray(): array
+    {
+        return [
+            'event' => $this->event,
+            'data' => $this->response->toArray(),
+        ];
+    }
+}

src/Responses/Images/EditStreamedResponse.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\Images;
+
+use OpenAI\Contracts\ResponseContract;
+use OpenAI\Exceptions\UnknownEventException;
+use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Responses\Images\Streaming\Error;
+use OpenAI\Responses\Images\Streaming\ImageGenerationCompleted;
+use OpenAI\Responses\Images\Streaming\ImageGenerationPartialImage;
+use OpenAI\Testing\Responses\Concerns\FakeableForStreamedResponse;
+
+/**
+ * @phpstan-type EditStreamedResponseType array{event: string, data: array<string, mixed>}
+ *
+ * @implements ResponseContract<EditStreamedResponseType>
+ */
+final class EditStreamedResponse implements ResponseContract
+{
+    /**
+     * @use ArrayAccessible<EditStreamedResponseType>
+     */
+    use ArrayAccessible;
+
+    use FakeableForStreamedResponse;
+
+    private function __construct(
+        public readonly string $event,
+        public readonly ImageGenerationPartialImage|ImageGenerationCompleted|Error $response,
+    ) {}
+
+    /**
+     * @param  array<string, mixed>  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        $event = $attributes['type'] ?? throw new UnknownEventException('Missing event type in streamed response');
+        $meta = $attributes['__meta'];
+        unset($attributes['__meta']);
+
+        $response = match ($event) {
+            'image_edit.partial_image' => ImageGenerationPartialImage::from($attributes, $meta), // @phpstan-ignore-line
+            'image_edit.completed' => ImageGenerationCompleted::from($attributes, $meta), // @phpstan-ignore-line
+            'error' => Error::from($attributes, $meta), // @phpstan-ignore-line
+            default => throw new UnknownEventException('Unknown Images streaming event: '.$event),
+        };
+
+        return new self(
+            event: $event, // @phpstan-ignore-line
+            response: $response,
+        );
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function toArray(): array
+    {
+        return [
+            'event' => $this->event,
+            'data' => $this->response->toArray(),
+        ];
+    }
+}

src/Responses/Images/ImageResponseUsage.php

@@ -14,7 +14,7 @@ private function __construct(
     ) {}
 
     /**
-     * @param  array{total_tokens: int, input_tokens?: int, output_tokens?: int, input_tokens_details?: array{text_tokens: int, image_tokens: int}}  $attributes
+     * @param  array{total_tokens: int, input_tokens?: int|null, output_tokens?: int|null, input_tokens_details?: array{text_tokens: int, image_tokens: int}|null}  $attributes
      */
     public static function from(array $attributes): self
     {

src/Responses/Images/Streaming/Error.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\Images\Streaming;
+
+use OpenAI\Contracts\ResponseContract;
+use OpenAI\Contracts\ResponseHasMetaInformationContract;
+use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Responses\Concerns\HasMetaInformation;
+use OpenAI\Responses\Meta\MetaInformation;
+use OpenAI\Testing\Responses\Concerns\Fakeable;
+
+/**
+ * @phpstan-type ErrorType array{type: string, code: string|null, message: string, param: string|null}
+ *
+ * @implements ResponseContract<ErrorType>
+ */
+final class Error implements ResponseContract, ResponseHasMetaInformationContract
+{
+    /**
+     * @use ArrayAccessible<ErrorType>
+     */
+    use ArrayAccessible;
+
+    use Fakeable;
+    use HasMetaInformation;
+
+    private function __construct(
+        public readonly string $type,
+        public readonly ?string $code,
+        public readonly string $message,
+        public readonly ?string $param,
+        private readonly MetaInformation $meta,
+    ) {}
+
+    /**
+     * @param  ErrorType  $attributes
+     */
+    public static function from(array $attributes, MetaInformation $meta): self
+    {
+        return new self(
+            type: $attributes['type'],
+            code: $attributes['code'],
+            message: $attributes['message'],
+            param: $attributes['param'],
+            meta: $meta,
+        );
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function toArray(): array
+    {
+        return [
+            'type' => $this->type,
+            'code' => $this->code,
+            'message' => $this->message,
+            'param' => $this->param,
+        ];
+    }
+}