### Connect and Stream with Odyssey Client in Vanilla JavaScript

Source: https://documentation.api.odyssey.ml/sdk/javascript/examples

This example shows how to initialize the Odyssey client, connect to the service, handle connection events (connected, disconnected, status change, errors), start a video stream with a prompt, interact with the stream, and disconnect. It requires the '@odysseyml/odyssey' package and DOM elements for video and status display.

```javascript
import { Odyssey } from '@odysseyml/odyssey';

const videoElement = document.getElementById('video');
const statusElement = document.getElementById('status');

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });

async function connect() {
  try {
    await client.connect({
      onConnected: (mediaStream) => {
        videoElement.srcObject = mediaStream;
        videoElement.play();
      },
      onDisconnected: () => {
        videoElement.srcObject = null;
      },
      onStatusChange: (status, message) => {
        statusElement.textContent = message || status;
      },
      onError: (error, fatal) => {
        console.error('Error:', error.message);
        if (fatal) {
          statusElement.textContent = 'Connection failed: ' + error.message;
        }
      },
    });
  } catch (error) {
    console.error('Failed to connect:', error.message);
    statusElement.textContent = 'Connection failed: ' + error.message;
  }
}

async function startStream() {
  const streamId = await client.startStream({ prompt: 'A cat', portrait: true });
  console.log('Stream started:', streamId);
}

async function interact(prompt) {
  const ack = await client.interact({ prompt });
  console.log('Acknowledged:', ack);
}

function disconnect() {
  client.disconnect();
}

// Usage
connect();
document.getElementById('start-btn').onclick = startStream;
document.getElementById('interact-btn').onclick = () => interact('Pet the cat');
document.getElementById('disconnect-btn').onclick = disconnect;
```

--------------------------------

### Record and Retrieve Video Streams with Python

Source: https://documentation.api.odyssey.ml/sdk/python/examples

Illustrates how to start a video stream, record it, and then retrieve the recording details and URL. It also shows how to list all available stream recordings.

```python
import asyncio
from odyssey import Odyssey

async def main():
    client = Odyssey(api_key="ody_your_api_key_here")
    stream_id = None

    try:
        await client.connect(on_video_frame=lambda f: None)

        # Start stream and save the ID
        stream_id = await client.start_stream("A sunset over the ocean")
        print(f"Stream ID: {stream_id}")

        await client.interact("Add some seagulls flying")
        await asyncio.sleep(5)
        await client.end_stream()

    finally:
        await client.disconnect()

    # Retrieve the recording (after disconnect is fine)
    if stream_id:
        recording = await client.get_recording(stream_id)
        print(f"Video URL: {recording.video_url}")
        print(f"Duration: {recording.duration_seconds}s")

        # List all recordings
        result = await client.list_stream_recordings(limit=5)
        print(f"Total recordings: {result.total}")
        for rec in result.recordings:
            print(f"  - {rec.stream_id}: {rec.duration_seconds}s")

asyncio.run(main())
```

--------------------------------

### Recording Workflow

Source: https://documentation.api.odyssey.ml/sdk/python/examples

Shows how to start a stream, interact with it, end the stream, and then retrieve the recording details, including video URL and duration.

```APIDOC
## Recording Workflow

### Description
This workflow demonstrates how to initiate a video stream, perform interactions, terminate the stream, and subsequently access the generated recording, including its video URL and duration.

### Method
Asynchronous Python functions using the `odyssey` library.

### Endpoint
N/A (Client-side library usage)

### Parameters
N/A

### Request Example
```python
import asyncio
from odyssey import Odyssey

async def main():
    client = Odyssey(api_key="ody_your_api_key_here")
    stream_id = None

    try:
        await client.connect(on_video_frame=lambda f: None)

        # Start stream and save the ID
        stream_id = await client.start_stream("A sunset over the ocean")
        print(f"Stream ID: {stream_id}")

        await client.interact("Add some seagulls flying")
        await asyncio.sleep(5)
        await client.end_stream()

    finally:
        await client.disconnect()

    # Retrieve the recording (after disconnect is fine)
    if stream_id:
        recording = await client.get_recording(stream_id)
        print(f"Video URL: {recording.video_url}")
        print(f"Duration: {recording.duration_seconds}s")

        # List all recordings
        result = await client.list_stream_recordings(limit=5)
        print(f"Total recordings: {result.total}")
        for rec in result.recordings:
            print(f"  - {rec.stream_id}: {rec.duration_seconds}s")

asyncio.run(main())
```

### Response
Prints Stream ID, Video URL, Duration, and a list of recordings.

#### Success Response (200)
N/A

#### Response Example
```
Stream ID: <stream_id>
Video URL: <video_url>
Duration: <duration_seconds>s
Total recordings: <total_count>
  - <stream_id_1>: <duration_seconds_1>s
  - <stream_id_2>: <duration_seconds_2>s
...
```
```

--------------------------------

### Image-to-Video

Source: https://documentation.api.odyssey.ml/sdk/python/examples

Enables the creation of videos starting from an image, with support for various image formats and automatic resizing.

```APIDOC
## Image-to-Video

### Description
This feature allows you to generate videos starting from a provided image. The API supports multiple image formats (JPEG, PNG, WebP, GIF, BMP, HEIC, HEIF, AVIF) and automatically resizes images to optimal dimensions (1280x704 or 704x1280). Requires SDK version 1.0.0+ and the image file size must not exceed 25MB.

### Method
Asynchronous Python functions using the `odyssey` library.

### Endpoint
N/A (Client-side library usage)

### Parameters
#### Request Body
- **prompt** (string) - Required - The initial prompt for the video.
- **image** (string or PIL.Image or bytes or numpy.ndarray) - Required - Path to the image file, a PIL Image object, bytes, or a NumPy array.
- **portrait** (boolean) - Optional - Specifies if the video should be in portrait mode (default is landscape).

### Request Example
```python
import asyncio
from odyssey import Odyssey, VideoFrame

frames = []

def on_frame(frame: VideoFrame) -> None:
    frames.append(frame.data.copy())

async def main():
    client = Odyssey(api_key="ody_your_api_key_here")

    try:
        # Connect to Odyssey
        await client.connect(
            on_video_frame=on_frame,
        )

        # Start stream with an image (file path)
        stream_id = await client.start_stream(
            prompt="A cat",
            portrait=False,
            image="/path/to/your/image.jpg"
        )
        print(f"Stream started: {stream_id}")

        # Interact as usual
        await client.interact("Pet the cat")
        await asyncio.sleep(5)

        await client.end_stream()
    finally:
        await client.disconnect()

    print(f"Collected {len(frames)} frames")

asyncio.run(main())
```

### Response
Starts a stream using the provided image and collects video frames. Prints the stream ID and the number of collected frames.

#### Success Response (200)
N/A

#### Response Example
```
Stream started: <stream_id>
Collected <frame_count> frames
```

### Request Example (Using PIL Image)
```python
from PIL import Image

# Using PIL Image
pil_image = Image.open("/path/to/image.jpg")
stream_id = await client.start_stream(prompt="A cat", image=pil_image)
```
```

--------------------------------

### Connect and Stream Video with Image and Text Prompt (JavaScript)

Source: https://documentation.api.odyssey.ml/api-quick-start

This example demonstrates connecting to the Odyssey API and initiating a video stream with both an image file and a text prompt. It handles UI updates for connection status and stream states, and includes logic for sending text prompts during an active stream or starting a new stream with an image. The Odyssey library is imported via ESM.

```javascript
import { Odyssey } from 'https://esm.sh/@odysseyml/odyssey';

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });
const status = document.getElementById('status');
const prompt = document.getElementById('prompt');
const imageInput = document.getElementById('image');
const sendBtn = document.getElementById('send');
const endBtn = document.getElementById('end');
let isStreaming = false;

window.addEventListener('beforeunload', () => client.disconnect());

document.getElementById('connect').onclick = () => {
  status.textContent = 'Connecting...';
  client.connect({
    onConnected: (mediaStream) => {
      document.getElementById('video').srcObject = mediaStream;
      prompt.disabled = false;
      sendBtn.disabled = false;
      status.textContent = 'Connected';
    },
    onStreamStarted: () => {
      isStreaming = true;
      endBtn.disabled = false;
      status.textContent = 'Streaming';
    },
    onStreamEnded: () => {
      isStreaming = false;
      endBtn.disabled = true;
      status.textContent = 'Connected';
    },
    onError: (error) => console.error('Error:', error.message),
  });
};

sendBtn.onclick = () => {
  const text = prompt.value.trim();
  prompt.value = '';
  if (isStreaming) {
    client.interact({ prompt: text });
  } else {
    const image = imageInput.files[0];
    client.startStream({ prompt: text, image });
  }
};

endBtn.onclick = () => client.endStream();
```

--------------------------------

### HTML Boilerplate for Odyssey Client Demo

Source: https://documentation.api.odyssey.ml/sdk/javascript/examples

This HTML boilerplate sets up the necessary elements (video player, status display, buttons) and includes a script to initialize and use the Odyssey client. It demonstrates connecting, starting a stream, interacting, and disconnecting, handling basic connection and error states.

```html
<!DOCTYPE html>
<html>
<head>
  <title>Odyssey Demo</title>
</head>
<body>
  <video id="video" autoplay playsinline muted></video>
  <p id="status">Disconnected</p>

  <button id="start-btn">Start Stream</button>
  <button id="interact-btn">Interact</button>
  <button id="disconnect-btn">Disconnect</button>

  <script type="module">
    import { Odyssey } from '@odysseyml/odyssey';

    const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });
    const video = document.getElementById('video');
    const status = document.getElementById('status');

    try {
      await client.connect({
        onConnected: (mediaStream) => {
          video.srcObject = mediaStream;
          status.textContent = 'Connected';
        },
        onError: (error, fatal) => {
          console.error('Error:', error.message);
          if (fatal) status.textContent = 'Connection failed';
        },
        onStatusChange: (s, msg) => {
          status.textContent = msg || s;
        },
      });

      document.getElementById('start-btn').onclick = async () => {
        await client.startStream({ prompt: 'A cat' });
      };
    } catch (error) {
      console.error('Failed to connect:', error.message);
      status.textContent = 'Connection failed';
    }

    document.getElementById('interact-btn').onclick = async () => {
      await client.interact({ prompt: 'Pet the cat' });
    };

    document.getElementById('disconnect-btn').onclick = () => {
      client.disconnect();
    };
  </script>
</body>
</html>
```

--------------------------------

### Generate Video from Image with Python

Source: https://documentation.api.odyssey.ml/sdk/python/examples

Explains how to use the Odyssey API to create a video starting from a provided image. It covers requirements, supported formats, and how to pass image data (file path, PIL Image, bytes, or NumPy array).

```python
import asyncio
from odyssey import Odyssey, VideoFrame

frames = []

def on_frame(frame: VideoFrame) -> None:
    frames.append(frame.data.copy())

async def main():
    client = Odyssey(api_key="ody_your_api_key_here")

    try:
        # Connect to Odyssey
        await client.connect(
            on_video_frame=on_frame,
        )

        # Start stream with an image (file path)
        stream_id = await client.start_stream(
            prompt="A cat",
            portrait=False,
            image="/path/to/your/image.jpg"
        )
        print(f"Stream started: {stream_id}")

        # Interact as usual
        await client.interact("Pet the cat")
        await asyncio.sleep(5)

        await client.end_stream()
    finally:
        await client.disconnect()

    print(f"Collected {len(frames)} frames")

asyncio.run(main())
```

```python
from PIL import Image

# Using PIL Image
pil_image = Image.open("/path/to/image.jpg")
stream_id = await client.start_stream(prompt="A cat", image=pil_image)
```

--------------------------------

### Example Simulation Script for Simulate API

Source: https://documentation.api.odyssey.ml/sdk/javascript/simulations

Provides a concrete example of a simulation script using the `ScriptEntry` interface. This script demonstrates starting a video, interacting with prompts at specific times, and ending the stream. It serves as a template for creating custom simulation sequences.

```typescript
const script = [
  // Start a portrait video of a cat at t=0
  { timestamp_ms: 0, start: { prompt: 'A cat sitting by a window' } },

  // Interact at t=3000ms (3 seconds)
  { timestamp_ms: 3000, interact: { prompt: 'The cat looks outside' } },

  // Another interaction at t=6000ms (6 seconds)
  { timestamp_ms: 6000, interact: { prompt: 'The cat stretches' } },

  // End the stream at t=9000ms (9 seconds)
  { timestamp_ms: 9000, end: {} }
];
```

--------------------------------

### Complete Example: Run and Monitor Simulation

Source: https://documentation.api.odyssey.ml/sdk/javascript/simulations

A comprehensive example demonstrating how to initialize the Odyssey client, create a simulation, poll for its status, and download recordings upon completion. Includes error handling for failed simulations.

```typescript
import { Odyssey } from '@odysseyml/odyssey';

async function runSimulation() {
  const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });

  // Create simulation
  const job = await client.simulate({
    script: [
      { timestamp_ms: 0, start: { prompt: 'A cat sitting on a windowsill' } },
      { timestamp_ms: 3000, interact: { prompt: 'The cat watches a bird outside' } },
      { timestamp_ms: 6000, interact: { prompt: 'The cat stretches lazily' } },
      { timestamp_ms: 9000, interact: { prompt: 'The cat curls up to sleep' } },
      { timestamp_ms: 12000, end: {} }
    ],
    portrait: true
  });

  console.log('Started simulation:', job.job_id);

  // Poll for completion
  let status;
  do {
    await new Promise(resolve => setTimeout(resolve, 5000));
    status = await client.getSimulateStatus(job.job_id);
    console.log('Status:', status.status);
  } while (status.status === 'pending' || status.status === 'running');

  if (status.status === 'completed') {
    // Download recordings
    for (const stream of status.streams) {
      const recording = await client.getRecording(stream.stream_id);
      console.log('Recording ready:', recording.video_url);
    }
  } else {
    console.error('Simulation failed:', status.error_message);
  }
}

runSimulation();
```

--------------------------------

### Complete Simulation Example

Source: https://documentation.api.odyssey.ml/sdk/python/simulations

This comprehensive Python example illustrates the end-to-end process of running a simulation, from creation to polling for completion and downloading recordings. It includes basic interaction prompts.

```python
import asyncio
from odyssey import Odyssey

async def run_simulation():
    client = Odyssey(api_key="ody_your_api_key_here")

    # Create simulation
    job = await client.simulate(
        script=[
            {"timestamp_ms": 0, "start": {"prompt": "A cat sitting on a windowsill"}},
            {"timestamp_ms": 3000, "interact": {"prompt": "The cat watches a bird outside"}},
            {"timestamp_ms": 6000, "interact": {"prompt": "The cat stretches lazily"}},
            {"timestamp_ms": 9000, "interact": {"prompt": "The cat curls up to sleep"}},
            {"timestamp_ms": 12000, "end": {}}
        ],
        portrait=True
    )

    print(f"Started simulation: {job.job_id}")

    # Poll for completion
    status = None
    while True:
        await asyncio.sleep(5)
        status = await client.get_simulate_status(job.job_id)
        print(f"Status: {status.status}")

        if status.status not in ("pending", "running"):
            break

    if status.status == "completed":
        # Download recordings
        for stream in status.streams:
            recording = await client.get_recording(stream.stream_id)
            print(f"Recording ready: {recording.video_url}")
    else:
        print(f"Simulation failed: {status.error_message}")

asyncio.run(run_simulation())
```

--------------------------------

### Next.js Text-to-Video with Callback Style Odyssey ML API

Source: https://documentation.api.odyssey.ml/api-quick-start

This example demonstrates text-to-video generation using the Odyssey ML API with a callback-based approach in Next.js. It shows how to handle connection events, stream status, and errors using provided callback functions. This style is an alternative to the async/await pattern for managing API interactions.

```tsx
'use client';
import { Odyssey } from '@odysseyml/odyssey';
import { useRef, useEffect, useState } from 'react';

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });

export default function OdysseyDemo() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const [prompt, setPrompt] = useState('');
  const [isConnected, setIsConnected] = useState(false);
  const [isStreaming, setIsStreaming] = useState(false);

  useEffect(() => () => client.disconnect(), []);

  const handleConnect = () => {
    client.connect({
      onConnected: (mediaStream) => {
        if (videoRef.current) videoRef.current.srcObject = mediaStream;
        setIsConnected(true);
      },
      onStreamStarted: () => setIsStreaming(true),
      onStreamEnded: () => setIsStreaming(false),
      onError: (error) => console.error('Error:', error.message),
    });
  };

  const handleSend = () => {
    const text = prompt;
    setPrompt('');
    isStreaming
      ? client.interact({ prompt: text })
      : client.startStream({ prompt: text });
  };

  return (
    <div>
      <video ref={videoRef} autoPlay playsInline muted style={{ width: '100%', background: '#000' }} />
      <button onClick={handleConnect} disabled={isConnected}>Connect</button>

```

--------------------------------

### Simulation API

Source: https://documentation.api.odyssey.ml/sdk/javascript/examples

This section covers the Simulation API, which allows for creating and running simulations with scripted sequences. It details how to define scripts, start simulations, monitor their status, and retrieve recordings.

```APIDOC
## Simulation API

### Description
Create and manage simulations with scripted events. The Simulate API requires SDK version 1.0.0 or higher. You can define a sequence of actions with timestamps and retrieve video recordings upon completion.

### Method
POST (Implicit via SDK method `client.simulate`)

### Endpoint
Not directly exposed; handled by the OdysseyML SDK.

### Parameters
#### Request Body (within `client.simulate`)
- **script** (Array<Object>) - Required - An array of objects, each defining an event at a specific `timestamp_ms`. Events can include `start`, `interact`, or `end` actions with associated prompts.
  - **timestamp_ms** (number) - Required - The time in milliseconds when the event should occur.
  - **start** (Object) - Optional - Defines the initial state or action.
    - **prompt** (string) - Required - The prompt for the starting action.
  - **interact** (Object) - Optional - Defines an interaction during the simulation.
    - **prompt** (string) - Required - The prompt for the interaction.
  - **end** (Object) - Optional - Marks the end of the simulation.
- **portrait** (boolean) - Optional - Set to `true` for portrait aspect ratio, `false` for landscape. Defaults to landscape.

### Request Example
```typescript
import { Odyssey } from '@odysseyml/odyssey';

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });

const job = await client.simulate({
  script: [
    { timestamp_ms: 0, start: { prompt: 'A cat sitting on a windowsill' } },
    { timestamp_ms: 3000, interact: { prompt: 'The cat watches a bird outside' } },
    { timestamp_ms: 6000, interact: { prompt: 'The cat stretches lazily' } },
    { timestamp_ms: 9000, end: {} }
  ],
  portrait: true
});

console.log('Simulation started:', job.job_id);

async function waitForCompletion(jobId: string) {
  while (true) {
    const status = await client.getSimulateStatus(jobId);
    if (status.status === 'completed') return status;
    if (status.status === 'failed') throw new Error(`Simulation failed: ${status.error_message}`);
    if (status.status === 'cancelled') throw new Error('Simulation was cancelled');
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

const result = await waitForCompletion(job.job_id);

for (const stream of result.streams) {
  const recording = await client.getRecording(stream.stream_id);
  console.log('Video URL:', recording.video_url);
}
```

### Response
#### Success Response (200)
- **job_id** (string) - The unique identifier for the simulation job.
- **streams** (Array<Object>) - An array of stream objects associated with the simulation.
  - **stream_id** (string) - The unique identifier for a stream within the simulation.

#### Status Response (via `client.getSimulateStatus`)
- **status** (string) - The current status of the simulation ('processing', 'completed', 'failed', 'cancelled').
- **error_message** (string) - If the status is 'failed', this contains the error details.

#### Recording Response (via `client.getRecording`)
- **video_url** (string) - The URL to the generated video recording.
```

--------------------------------

### Complete Odyssey API Workflow Example in Python

Source: https://documentation.api.odyssey.ml/sdk/python/recordings

Demonstrates the end-to-end process of using the Odyssey API. This includes connecting to the service, starting an interactive stream with a prompt, sending subsequent interactions, managing the stream's duration, ending the stream, and finally retrieving the recording URL and duration. It handles potential connection errors and ensures disconnection.

```python
import asyncio
from odyssey import Odyssey, OdysseyConnectionError

async def main():
    client = Odyssey(api_key="ody_your_api_key_here")

    try:
        await client.connect(
            on_video_frame=lambda frame: print(f"Frame: {frame.width}x{frame.height}"),
        )

        # Start an interactive stream and capture the stream ID
        stream_id = await client.start_stream("A cat sitting on a windowsill", portrait=True)
        print(f"Stream started: {stream_id}")

        # Send some interactions
        await client.interact("The cat stretches and yawns")
        await client.interact("The cat looks outside at birds")

        # Let it run for a bit
        await asyncio.sleep(5)

        # End the stream
        await client.end_stream()

    except OdysseyConnectionError as e:
        print(f"Connection failed: {e}")
    finally:
        await client.disconnect()

    # Retrieve the recording (can be done after disconnect)
    recording = await client.get_recording(stream_id)

    if recording.video_url:
        print(f"Recording available at: {recording.video_url}")
        print(f"Duration: {recording.duration_seconds} seconds")

asyncio.run(main())
```

--------------------------------

### Image-to-Video Generation with Callbacks (JavaScript)

Source: https://documentation.api.odyssey.ml/api-quick-start

Generates a video stream from an image file and a text prompt using the Odyssey ML API with callbacks. This example handles image input and stream events via dedicated functions. Remember to disconnect.

```typescript
import { Odyssey } from '@odysseyml/odyssey';

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });
const imageFile = document.querySelector('input[type="file"]').files[0];

client.connect({
  onConnected: (mediaStream) => {
    document.querySelector('video').srcObject = mediaStream;
    client.startStream({ prompt: 'A cat', image: imageFile });
  },
  onStreamStarted: () => {
    client.interact({ prompt: 'Pet the cat' });
  },
  onInteractAcknowledged: () => {
    client.endStream();
  },
  onStreamEnded: () => {
    client.disconnect();
  },
  onError: (error, fatal) => {
    console.error('Error:', error.message, 'Fatal:', fatal);
  },
});
```

--------------------------------

### Python: Text-to-Video Stream with Odyssey

Source: https://documentation.api.odyssey.ml/api-quick-start

This Python script demonstrates how to use the Odyssey SDK to generate video from text prompts asynchronously. It includes connection handling, starting a stream with a text prompt, interacting with the stream, and properly disconnecting. Error handling for authentication and connection issues is also provided.

```python
import asyncio
from odyssey import Odyssey, OdysseyAuthError, OdysseyConnectionError

async def main():
    client = Odyssey(api_key="ody_your_api_key_here")

    try:
        await client.connect(
            on_video_frame=lambda frame: print(f"Frame: {frame.width}x{frame.height}"),
            on_stream_started=lambda stream_id: print(f"Ready: {stream_id}"),
        )
        await client.start_stream("A cat", portrait=True)
        await client.interact("Pet the cat")
        await client.end_stream()
    except OdysseyAuthError:
        print("Invalid API key")
    except OdysseyConnectionError as e:
        print(f"Connection failed: {e}")
    finally:
        await client.disconnect()

asyncio.run(main())
```

--------------------------------

### Simulate Scenarios with Scripted Sequences using TypeScript

Source: https://documentation.api.odyssey.ml/sdk/javascript/examples

This TypeScript example shows how to utilize the Odyssey ML Simulate API to create and manage simulations based on a scripted sequence of events. It requires SDK version 1.0.0 or higher. The process includes defining a script with timestamps and actions, starting the simulation, polling for its completion status, and retrieving recordings.

```typescript
import { Odyssey } from '@odysseyml/odyssey';

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });

// Create a simulation with a scripted sequence
const job = await client.simulate({
  script: [
    { timestamp_ms: 0, start: { prompt: 'A cat sitting on a windowsill' } },
    { timestamp_ms: 3000, interact: { prompt: 'The cat watches a bird outside' } },
    { timestamp_ms: 6000, interact: { prompt: 'The cat stretches lazily' } },
    { timestamp_ms: 9000, end: {} }
  ],
  portrait: true
});

console.log('Simulation started:', job.job_id);

// Poll for completion
async function waitForCompletion(jobId: string) {
  while (true) {
    const status = await client.getSimulateStatus(jobId);

    if (status.status === 'completed') {
      return status;
    }
    if (status.status === 'failed') {
      throw new Error(`Simulation failed: ${status.error_message}`);
    }
    if (status.status === 'cancelled') {
      throw new Error('Simulation was cancelled');
    }

    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

const result = await waitForCompletion(job.job_id);

// Get recordings from completed simulation
for (const stream of result.streams) {
  const recording = await client.getRecording(stream.stream_id);
  console.log('Video URL:', recording.video_url);
}
```

--------------------------------

### Text-to-Video Generation with Odyssey ML (JavaScript)

Source: https://documentation.api.odyssey.ml/api-quick-start

Generates a video stream from a text prompt using the Odyssey ML API. This example uses async/await for managing asynchronous operations. Ensure you call `disconnect()` when finished to avoid exceeding session limits.

```typescript
import { Odyssey } from '@odysseyml/odyssey';

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });

const mediaStream = await client.connect();
document.querySelector('video').srcObject = mediaStream;

await client.startStream({ prompt: 'A cat' });
await client.interact({ prompt: 'Pet the cat' });
await client.endStream();
client.disconnect();
```

--------------------------------

### Python: Image-to-Video Stream with Odyssey

Source: https://documentation.api.odyssey.ml/api-quick-start

This Python script shows how to generate video from an initial image and a text prompt using the Odyssey SDK asynchronously. It covers connecting to the service, starting a stream with an image file path and prompt, interacting with the generated video, and ensuring a clean disconnection. It also includes error handling for common issues.

```python
import asyncio
from odyssey import Odyssey, OdysseyAuthError, OdysseyConnectionError

async def main():
    client = Odyssey(api_key="ody_your_api_key_here")

    try:
        await client.connect(
            on_video_frame=lambda frame: print(f"Frame: {frame.width}x{frame.height}"),
            on_stream_started=lambda stream_id: print(f"Ready: {stream_id}"),
        )
        # Start with an image file
        await client.start_stream(
            prompt="A cat",
            portrait=False,
            image_path="/path/to/image.jpg"
        )
        await client.interact("Pet the cat")
        await client.end_stream()
    except OdysseyAuthError:
        print("Invalid API key")
    except OdysseyConnectionError as e:
        print(f"Connection failed: {e}")
    finally:
        await client.disconnect()

asyncio.run(main())
```

--------------------------------

### Use Odyssey Hook for Video Generation (React)

Source: https://documentation.api.odyssey.ml/api-quick-start

Provides a React hook-based approach (`useOdyssey`) for interacting with the Odyssey ML API. This example covers text-to-video generation, managing connection status, and streaming controls within a functional component.

```tsx
import { useOdyssey } from '@odysseyml/odyssey/react';
import { useRef, useEffect, useState } from 'react';

function App() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const [prompt, setPrompt] = useState('');
  const [isConnected, setIsConnected] = useState(false);
  const [isStreaming, setIsStreaming] = useState(false);

  const odyssey = useOdyssey({
    apiKey: 'ody_your_api_key_here',
    handlers: {
      onConnected: (mediaStream) => {
        if (videoRef.current) videoRef.current.srcObject = mediaStream;
        setIsConnected(true);
      },
      onStreamStarted: () => setIsStreaming(true),
      onStreamEnded: () => setIsStreaming(false),
      onDisconnected: () => {
        setIsConnected(false);
        setIsStreaming(false);
      },
      onError: (error) => console.error('Error:', error.message),
    },
  });

  useEffect(() => {
    return () => odyssey.disconnect();
  }, []);

  const handleSend = () => {
    const text = prompt;
    setPrompt('');
    isStreaming
      ? odyssey.interact({ prompt: text })
      : odyssey.startStream({ prompt: text });
  };

  return (
    <div>
      <video ref={videoRef} autoPlay playsInline muted />
      <p>Status: {odyssey.status}</p>
      <button onClick={() => odyssey.connect()} disabled={isConnected}>Connect</button>
      <input value={prompt} onChange={(e) => setPrompt(e.target.value)} placeholder="Enter prompt..." disabled={!isConnected} />
      <button onClick={handleSend} disabled={!isConnected}>Send</button>
      <button onClick={() => odyssey.endStream()} disabled={!isStreaming}>End</button>
    </div>
  );
}
```

--------------------------------

### Image-to-Video Generation with Odyssey ML (JavaScript)

Source: https://documentation.api.odyssey.ml/api-quick-start

Generates a video stream from an image file and a text prompt using the Odyssey ML API. This example uses async/await and requires an image file input. Remember to call `disconnect()` to manage your connection.

```typescript
import { Odyssey } from '@odysseyml/odyssey';

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });

const mediaStream = await client.connect();
document.querySelector('video').srcObject = mediaStream;

// Get image from file input
const imageFile = document.querySelector('input[type="file"]').files[0];

await client.startStream({ prompt: 'A cat', image: imageFile });
await client.interact({ prompt: 'Pet the cat' });
await client.endStream();
client.disconnect();
```

--------------------------------

### Image-to-Video Generation

Source: https://documentation.api.odyssey.ml/sdk/javascript/examples

This section details how to generate video from a static image using the OdysseyML SDK. It outlines the necessary requirements, supported formats, and provides a code example for initiating a video stream from an image.

```APIDOC
## Image-to-Video Generation

### Description
Generate video content from a static image file. This feature requires SDK version 1.0.0+ and supports various image formats. Images will be resized to a standard aspect ratio before processing.

### Method
POST (Implicit via SDK method `client.startStream`)

### Endpoint
Not directly exposed; handled by the OdysseyML SDK.

### Parameters
#### Request Body (within `client.startStream`)
- **image** (File) - Required - The image file to convert into a video.
- **prompt** (string) - Required - A text description to guide the video generation.
- **portrait** (boolean) - Optional - Set to `true` for portrait aspect ratio (704x1280), `false` for landscape (1280x704). Defaults to landscape.

### Request Example
```typescript
import { Odyssey } from '@odysseyml/odyssey';

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });
const fileInput = document.getElementById('image-input') as HTMLInputElement;

fileInput.addEventListener('change', async () => {
  const imageFile = fileInput.files?.[0];
  if (!imageFile) return;

  const mediaStream = await client.connect();
  document.querySelector('video').srcObject = mediaStream;

  const streamId = await client.startStream({
    prompt: 'A cat',
    portrait: false, // landscape
    image: imageFile
  });
  console.log('Stream started:', streamId);
});

window.addEventListener('beforeunload', () => client.disconnect());
```

### Response
#### Success Response (Implicit via SDK)
- **streamId** (string) - The unique identifier for the started video stream.
```

--------------------------------

### React Text-to-Video with Odyssey ML (Callback Style)

Source: https://documentation.api.odyssey.ml/api-quick-start

This example shows how to use the Odyssey ML API for text-to-video generation in React using a callback-based approach. It handles connection events, stream status updates, and error handling through provided callback functions. Requires '@odysseyml/odyssey'.

```tsx
import { Odyssey } from '@odysseyml/odyssey';
import { useRef, useEffect, useState } from 'react';

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });

function App() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const [prompt, setPrompt] = useState('');
  const [isConnected, setIsConnected] = useState(false);
  const [isStreaming, setIsStreaming] = useState(false);

  useEffect(() => {
    return () => client.disconnect();
  }, []);

  const handleConnect = () => {
    client.connect({
      onConnected: (mediaStream) => {
        if (videoRef.current) videoRef.current.srcObject = mediaStream;
        setIsConnected(true);
      },
      onStreamStarted: () => setIsStreaming(true),
      onStreamEnded: () => setIsStreaming(false),
      onError: (error) => console.error('Error:', error.message),
    });
  };

  const handleSend = () => {
    const text = prompt;
    setPrompt('');
    isStreaming
      ? client.interact({ prompt: text })
      : client.startStream({ prompt: text });

```

--------------------------------

### Simulate API

Source: https://documentation.api.odyssey.ml/sdk/python/examples

This section details how to use the Simulate API to create and manage simulations. It requires SDK version 1.0.0 or higher.

```APIDOC
## POST /simulate

### Description
Creates a simulation with a scripted sequence of events.

### Method
POST

### Endpoint
/simulate

### Parameters
#### Query Parameters
- **portrait** (boolean) - Optional - If true, the simulation will be in portrait mode.

#### Request Body
- **script** (array) - Required - A list of actions with timestamps.
  - **timestamp_ms** (integer) - Required - The timestamp in milliseconds when the action should occur.
  - **start** (object) - Optional - Defines the start of an interaction.
    - **prompt** (string) - Required - The prompt for the start action.
  - **interact** (object) - Optional - Defines an interaction during the simulation.
    - **prompt** (string) - Required - The prompt for the interaction.
  - **end** (object) - Optional - Defines the end of the simulation.

### Request Example
```json
{
  "script": [
    {"timestamp_ms": 0, "start": {"prompt": "A cat sitting on a windowsill"}},
    {"timestamp_ms": 3000, "interact": {"prompt": "The cat watches a bird outside"}},
    {"timestamp_ms": 6000, "interact": {"prompt": "The cat stretches lazily"}},
    {"timestamp_ms": 9000, "end": {}}
  ],
  "portrait": true
}
```

### Response
#### Success Response (200)
- **job_id** (string) - The ID of the created simulation job.

#### Response Example
```json
{
  "job_id": "sim_abc123xyz"
}
```
```

```APIDOC
## GET /simulate/status/{job_id}

### Description
Retrieves the status of a simulation job.

### Method
GET

### Endpoint
/simulate/status/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the simulation job.

### Response
#### Success Response (200)
- **status** (string) - The current status of the simulation (e.g., 'processing', 'completed', 'failed', 'cancelled').
- **error_message** (string) - If the status is 'failed', this field contains the error message.
- **streams** (array) - A list of streams associated with the simulation.
  - **stream_id** (string) - The ID of the stream.

#### Response Example
```json
{
  "status": "completed",
  "streams": [
    {"stream_id": "stream_12345"}
  ]
}
```
```

```APIDOC
## GET /recording/{stream_id}

### Description
Retrieves the recording for a given stream ID.

### Method
GET

### Endpoint
/recording/{stream_id}

### Parameters
#### Path Parameters
- **stream_id** (string) - Required - The ID of the stream for which to retrieve the recording.

### Response
#### Success Response (200)
- **video_url** (string) - The URL to the video recording.

#### Response Example
```json
{
  "video_url": "https://example.com/recordings/video.mp4"
}
```
```

--------------------------------

### Status Monitoring with Odyssey Python Client

Source: https://documentation.api.odyssey.ml/sdk/python/examples

This example demonstrates how to monitor the connection status of the Odyssey Python client. It defines a callback function to handle different connection states and prints messages accordingly. Requires the 'odyssey' library.

```python
import asyncio
from odyssey import Odyssey, ConnectionStatus

def on_status_change(status: ConnectionStatus, message: str | None) -> None:
    match status:
        case ConnectionStatus.AUTHENTICATING:
            print("Authenticating...")
        case ConnectionStatus.CONNECTING:
            print("Connecting to server...")
        case ConnectionStatus.RECONNECTING:
            print("Reconnecting...")
        case ConnectionStatus.CONNECTED:
            print("Connected and ready!")
        case ConnectionStatus.DISCONNECTED:
            print("Disconnected")
        case ConnectionStatus.FAILED:
            print(f"Connection failed: {message or 'Unknown error'}")

async def main():
    client = Odyssey(api_key="ody_your_api_key_here")

    await client.connect(
        on_video_frame=lambda f: None,
        on_status_change=on_status_change,
    )

    # ... use the client ...

    await client.disconnect()

asyncio.run(main())

```

--------------------------------

### Connect and Stream Video with Text Prompt (JavaScript)

Source: https://documentation.api.odyssey.ml/api-quick-start

This snippet shows how to connect to the Odyssey API, handle connection events, and start a video stream using a text prompt. It manages UI elements for connection status, input fields, and buttons. Dependencies include the Odyssey library imported via ESM.

```javascript
import { Odyssey } from 'https://esm.sh/@odysseyml/odyssey';

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });
const status = document.getElementById('status');
const prompt = document.getElementById('prompt');
const sendBtn = document.getElementById('send');
const endBtn = document.getElementById('end');
let isStreaming = false;

window.addEventListener('beforeunload', () => client.disconnect());

document.getElementById('connect').onclick = () => {
  status.textContent = 'Connecting...';
  client.connect({
    onConnected: (mediaStream) => {
      document.getElementById('video').srcObject = mediaStream;
      prompt.disabled = false;
      sendBtn.disabled = false;
      status.textContent = 'Connected';
    },
    onStreamStarted: () => {
      isStreaming = true;
      endBtn.disabled = false;
      status.textContent = 'Streaming';
    },
    onStreamEnded: () => {
      isStreaming = false;
      endBtn.disabled = true;
      status.textContent = 'Connected';
    },
    onError: (error) => console.error('Error:', error.message),
  });
};

sendBtn.onclick = () => {
  const text = prompt.value.trim();
  if (!text) return;
  prompt.value = '';
  isStreaming ? client.interact({ prompt: text }) : client.startStream({ prompt: text });
};

endBtn.onclick = () => client.endStream();
```

--------------------------------

### Generate Video from Image using TypeScript

Source: https://documentation.api.odyssey.ml/sdk/javascript/examples

This snippet demonstrates how to use the Odyssey ML SDK in TypeScript to generate a video stream from a static image. It requires SDK version 1.0.0+, supports various image formats, and resizes images to specific dimensions. The process involves connecting to the client, starting a stream with an image, and interacting with the generated video.

```typescript
import { Odyssey } from '@odysseyml/odyssey';

const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });

// File input handler
const fileInput = document.getElementById('image-input') as HTMLInputElement;

fileInput.addEventListener('change', async () => {
  const imageFile = fileInput.files?.[0];
  if (!imageFile) return;

  // Connect to Odyssey
  const mediaStream = await client.connect();
  document.querySelector('video').srcObject = mediaStream;

  // Start stream with the image
  const streamId = await client.startStream({
    prompt: 'A cat',
    portrait: false, // landscape
    image: imageFile
  });
  console.log('Stream started:', streamId);

  // Interact as usual
  await client.interact({ prompt: 'Pet the cat' });
});

// Cleanup
window.addEventListener('beforeunload', () => client.disconnect());
```

--------------------------------

### Install Odyssey JavaScript Client

Source: https://documentation.api.odyssey.ml/sdk/javascript/introduction

Install the Odyssey JavaScript client library using npm, yarn, or pnpm. This package provides a TypeScript/JavaScript client for interacting with Odyssey's audio-visual intelligence.

```bash
npm install @odysseyml/odyssey
```

```bash
yarn add @odysseyml/odyssey
```

```bash
pnpm add @odysseyml/odyssey
```

--------------------------------

### HTML Text-to-Video Streaming with Odyssey ML API

Source: https://documentation.api.odyssey.ml/api-quick-start

This snippet shows how to implement text-to-video streaming using the Odyssey ML API in a standalone HTML file. It connects to the API, allows users to input text prompts, and displays the generated video stream. Dependencies include the Odyssey JavaScript library imported via CDN. It handles starting, interacting with, and ending the video stream.

```html
<!DOCTYPE html>
<html>
<head>
  <style>
    body { font-family: system-ui; max-width: 600px; margin: 2rem auto; }
    video { width: 100%; background: #000; }
    input[type="text"] { flex: 1; padding: 0.5rem; }
    button { padding: 0.5rem 1rem; }
    .row { display: flex; gap: 0.5rem; margin-top: 0.5rem; }
  </style>
</head>
<body>
  <video id="video" autoplay playsinline muted></video>
  <p id="status">Loading...</p>
  <div class="row">
    <input id="prompt" type="text" placeholder="Enter prompt..." />
    <button id="send">Send</button>
    <button id="end" disabled>End</button>
  </div>
  <script type="module">
    import { Odyssey } from 'https://esm.sh/@odysseyml/odyssey';

    const client = new Odyssey({ apiKey: 'ody_your_api_key_here' });
    const status = document.getElementById('status');
    const prompt = document.getElementById('prompt');
    const endBtn = document.getElementById('end');
    let isStreaming = false;

    window.addEventListener('beforeunload', () => client.disconnect());

    status.textContent = 'Connecting...';
    const mediaStream = await client.connect();
    document.getElementById('video').srcObject = mediaStream;
    status.textContent = 'Connected';

    document.getElementById('send').onclick = async () => {
      const text = prompt.value.trim();
      if (!text) return;
      prompt.value = '';

      if (isStreaming) {
        await client.interact({ prompt: text });
      } else {
        status.textContent = 'Starting...';
        await client.startStream({ prompt: text });
        isStreaming = true;
        endBtn.disabled = false;
        status.textContent = 'Streaming';
      }
    };

    endBtn.onclick = async () => {
      await client.endStream();
      isStreaming = false;
      endBtn.disabled = true;
      status.textContent = 'Connected';
    };
  </script>
</body>
</html>
```