feat(OpenAI): Realtime Ephermal Tokens (#591)

* feat: initial work on realtime tokens

* feat: more work on realtime tokens

* fix: add realtime class to client

* fix: threshold is float, not int

* fix: modalities can be null on transcribe

* feat: test build out for realtime

* chore: correct docblock

* test: integration tests for realtime

Author: iBotPeaches

src/Client.php

@@ -5,6 +5,7 @@
 namespace OpenAI;
 
 use OpenAI\Contracts\ClientContract;
+use OpenAI\Contracts\Resources\RealtimeContract;
 use OpenAI\Contracts\Resources\ThreadsContract;
 use OpenAI\Contracts\Resources\VectorStoresContract;
 use OpenAI\Contracts\TransporterContract;
@@ -21,6 +22,7 @@
 use OpenAI\Resources\Images;
 use OpenAI\Resources\Models;
 use OpenAI\Resources\Moderations;
+use OpenAI\Resources\Realtime;
 use OpenAI\Resources\Responses;
 use OpenAI\Resources\Threads;
 use OpenAI\Resources\VectorStores;
@@ -168,6 +170,16 @@ public function assistants(): Assistants
         return new Assistants($this->transporter);
     }
 
+    /**
+     * Communicate with a model in real time using WebRTC or WebSockets.
+     *
+     * @see https://platform.openai.com/docs/api-reference/realtime
+     */
+    public function realtime(): RealtimeContract
+    {
+        return new Realtime($this->transporter);
+    }
+
     /**
      * Create threads that assistants can interact with.
      *

src/Contracts/ClientContract.php

@@ -15,6 +15,7 @@
 use OpenAI\Contracts\Resources\ImagesContract;
 use OpenAI\Contracts\Resources\ModelsContract;
 use OpenAI\Contracts\Resources\ModerationsContract;
+use OpenAI\Contracts\Resources\RealtimeContract;
 use OpenAI\Contracts\Resources\ResponsesContract;
 use OpenAI\Contracts\Resources\ThreadsContract;
 use OpenAI\Contracts\Resources\VectorStoresContract;
@@ -36,6 +37,13 @@ public function completions(): CompletionsContract;
      */
     public function responses(): ResponsesContract;
 
+    /**
+     * Communicate with a GPT-4o class model in real time using WebRTC or WebSockets. Supports text and audio inputs and outputs, along with audio transcriptions.
+     *
+     * @see https://platform.openai.com/docs/api-reference/realtime-sessions
+     */
+    public function realtime(): RealtimeContract;
+
     /**
      * Given a chat conversation, the model will return a chat completion response.
      *

src/Contracts/Resources/RealtimeContract.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Realtime\SessionResponse;
+use OpenAI\Responses\Realtime\TranscriptionSessionResponse;
+
+interface RealtimeContract
+{
+    /**
+     * Create an ephemeral API token for real time sessions.
+     *
+     * @see https://platform.openai.com/docs/api-reference/realtime-sessions/create
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function token(array $parameters = []): SessionResponse;
+
+    /**
+     * Create an ephemeral API token for real time transcription sessions.
+     *
+     * @see https://platform.openai.com/docs/api-reference/realtime-sessions/create-transcription
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function transcribeToken(array $parameters = []): TranscriptionSessionResponse;
+}

src/Resources/Realtime.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Resources;
+
+use OpenAI\Contracts\Resources\RealtimeContract;
+use OpenAI\Responses\Realtime\SessionResponse;
+use OpenAI\Responses\Realtime\TranscriptionSessionResponse;
+use OpenAI\ValueObjects\Transporter\Payload;
+use OpenAI\ValueObjects\Transporter\Response;
+
+/**
+ * @phpstan-import-type SessionType from SessionResponse
+ * @phpstan-import-type TranscriptionSessionType from TranscriptionSessionResponse
+ */
+final class Realtime implements RealtimeContract
+{
+    use Concerns\Transportable;
+
+    /**
+     * Create an ephemeral API token for real time sessions.
+     *
+     * @see https://platform.openai.com/docs/api-reference/realtime-sessions/create
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function token(array $parameters = []): SessionResponse
+    {
+        $payload = Payload::create('realtime/sessions', $parameters);
+
+        /** @var Response<SessionType> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return SessionResponse::from($response->data());
+    }
+
+    /**
+     * Create an ephemeral API token for real time transcription sessions.
+     *
+     * @see https://platform.openai.com/docs/api-reference/realtime-sessions/create-transcription
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function transcribeToken(array $parameters = []): TranscriptionSessionResponse
+    {
+        $payload = Payload::create('realtime/transcription_sessions', $parameters);
+
+        /** @var Response<TranscriptionSessionType> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return TranscriptionSessionResponse::from($response->data());
+    }
+}

src/Responses/Realtime/Session/ClientSecret.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\Realtime\Session;
+
+use OpenAI\Contracts\ResponseContract;
+use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Testing\Responses\Concerns\Fakeable;
+
+/**
+ * @phpstan-type ClientSecretType array{expires_at: int, value: string}
+ *
+ * @implements ResponseContract<ClientSecretType>
+ */
+final class ClientSecret implements ResponseContract
+{
+    /**
+     * @use ArrayAccessible<ClientSecretType>
+     */
+    use ArrayAccessible;
+
+    use Fakeable;
+
+    private function __construct(
+        public readonly int $expiresAt,
+        public readonly string $value,
+    ) {}
+
+    /**
+     * @param  ClientSecretType  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            expiresAt: $attributes['expires_at'],
+            value: $attributes['value'],
+        );
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function toArray(): array
+    {
+        return [
+            'expires_at' => $this->expiresAt,
+            'value' => $this->value,
+        ];
+    }
+}

src/Responses/Realtime/Session/InputAudioTranscription.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\Realtime\Session;
+
+use OpenAI\Contracts\ResponseContract;
+use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Testing\Responses\Concerns\Fakeable;
+
+/**
+ * @phpstan-type InputAudioTranscriptionType array{model: 'whisper-1'}
+ *
+ * @implements ResponseContract<InputAudioTranscriptionType>
+ */
+final class InputAudioTranscription implements ResponseContract
+{
+    /**
+     * @use ArrayAccessible<InputAudioTranscriptionType>
+     */
+    use ArrayAccessible;
+
+    use Fakeable;
+
+    /**
+     * @param  "whisper-1"  $model
+     */
+    private function __construct(
+        public readonly string $model
+    ) {}
+
+    /**
+     * @param  InputAudioTranscriptionType  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            model: $attributes['model'],
+        );
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function toArray(): array
+    {
+        return [
+            'model' => $this->model,
+        ];
+    }
+}

src/Responses/Realtime/Session/TurnDetection.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\Realtime\Session;
+
+use OpenAI\Contracts\ResponseContract;
+use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Testing\Responses\Concerns\Fakeable;
+
+/**
+ * @phpstan-type TurnDetectionType array{prefix_padding_ms: int, silence_duration_ms: int, threshold: float, type: 'server_vad'}
+ *
+ * @implements ResponseContract<TurnDetectionType>
+ */
+final class TurnDetection implements ResponseContract
+{
+    /**
+     * @use ArrayAccessible<TurnDetectionType>
+     */
+    use ArrayAccessible;
+
+    use Fakeable;
+
+    /**
+     * @param  'server_vad'  $type
+     */
+    private function __construct(
+        public readonly int $prefixPaddingMs,
+        public readonly int $silenceDurationMs,
+        public readonly float $threshold,
+        public readonly string $type,
+    ) {}
+
+    /**
+     * @param  TurnDetectionType  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            prefixPaddingMs: $attributes['prefix_padding_ms'],
+            silenceDurationMs: $attributes['silence_duration_ms'],
+            threshold: $attributes['threshold'],
+            type: $attributes['type'],
+        );
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function toArray(): array
+    {
+        return [
+            'prefix_padding_ms' => $this->prefixPaddingMs,
+            'silence_duration_ms' => $this->silenceDurationMs,
+            'threshold' => $this->threshold,
+            'type' => $this->type,
+        ];
+    }
+}