> ## Documentation Index > Fetch the complete documentation index at: https://documentation.api.odyssey.ml/llms.txt > Use this file to discover all available pages before exploring further. # API Quick Start > Integrate Odyssey-2 Pro into your application in 5 minutes. ## Create a developer account & get an API key Sign up and receive an API key at [developer.odyssey.ml](https://developer.odyssey.ml/dashboard). ## Install ```bash npm theme={null} npm install @odysseyml/odyssey ``` ```bash yarn theme={null} yarn add @odysseyml/odyssey ``` ```bash pnpm theme={null} pnpm add @odysseyml/odyssey ``` npm package version `"@odysseyml/odyssey": "^1.0.0" required` ### Image-to-Video Requirements For image-to-video generation: * **Max size**: 25MB * **Supported formats**: JPEG, PNG, WebP, GIF, BMP, HEIC, HEIF, AVIF * **Resolution**: Images are automatically resized to 1280x704 (landscape) or 704x1280 (portrait) ## HTML For standalone HTML files without a bundler, import directly from a CDN: ```html Text-to-Video theme={null}

Loading...

``` ```html Image-to-Video theme={null}

Loading...

``` ```html Text-to-Video theme={null}

Disconnected

``` ```html Image-to-Video theme={null}

Disconnected

``` Always ensure `disconnect()` is called when done (via page unload handlers or component cleanup). Stale connections count towards your concurrent session limit, which will block new connections until they time out. If `disconnect()` is not called, idle connections are automatically cleared after 15 minutes on the server side. ## JavaScript ```typescript Text-to-Video theme={null} 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(); ``` ```typescript Image-to-Video theme={null} 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(); ``` ```typescript Text-to-Video theme={null} import { Odyssey } from '@odysseyml/odyssey'; const client = new Odyssey({ apiKey: 'ody_your_api_key_here' }); client.connect({ onConnected: (mediaStream) => { document.querySelector('video').srcObject = mediaStream; client.startStream({ prompt: 'A cat' }); }, onStreamStarted: () => { client.interact({ prompt: 'Pet the cat' }); }, onInteractAcknowledged: () => { client.endStream(); }, onStreamEnded: () => { client.disconnect(); }, onError: (error, fatal) => { console.error('Error:', error.message, 'Fatal:', fatal); }, }); ``` ```typescript Image-to-Video theme={null} 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); }, }); ``` ## React ```tsx Text-to-Video theme={null} 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(null); const [prompt, setPrompt] = useState(''); const [status, setStatus] = useState('Disconnected'); const [isConnected, setIsConnected] = useState(false); const [isStreaming, setIsStreaming] = useState(false); useEffect(() => { return () => client.disconnect(); }, []); const handleConnect = async () => { setStatus('Connecting...'); const mediaStream = await client.connect(); if (videoRef.current) videoRef.current.srcObject = mediaStream; setIsConnected(true); setStatus('Connected'); }; const handleSend = async () => { if (!prompt.trim()) return; const text = prompt; setPrompt(''); if (isStreaming) { await client.interact({ prompt: text }); } else { setStatus('Starting...'); await client.startStream({ prompt: text }); setIsStreaming(true); setStatus('Streaming'); } }; return (
); } ``` ```tsx Image-to-Video theme={null} 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(null); const [prompt, setPrompt] = useState(''); const [image, setImage] = useState(null); const [status, setStatus] = useState('Disconnected'); const [isConnected, setIsConnected] = useState(false); const [isStreaming, setIsStreaming] = useState(false); useEffect(() => { return () => client.disconnect(); }, []); const handleConnect = async () => { setStatus('Connecting...'); const mediaStream = await client.connect(); if (videoRef.current) videoRef.current.srcObject = mediaStream; setIsConnected(true); setStatus('Connected'); }; const handleSend = async () => { const text = prompt; setPrompt(''); if (isStreaming) { await client.interact({ prompt: text }); } else { setStatus('Starting...'); await client.startStream({ prompt: text, image: image || undefined }); setIsStreaming(true); setStatus('Streaming'); } }; return (
); } ``` ```tsx Text-to-Video theme={null} 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(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 }); }; return (
); } ``` ```tsx Image-to-Video theme={null} 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(null); const [prompt, setPrompt] = useState(''); const [image, setImage] = useState(null); 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, image: image || undefined }); }; return (
); } ``` ```tsx Text-to-Video theme={null} import { useOdyssey } from '@odysseyml/odyssey/react'; import { useRef, useEffect, useState } from 'react'; function App() { const videoRef = useRef(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 (
); } ``` ```tsx Image-to-Video theme={null} import { useOdyssey } from '@odysseyml/odyssey/react'; import { useRef, useEffect, useState } from 'react'; function App() { const videoRef = useRef(null); const [prompt, setPrompt] = useState(''); const [image, setImage] = useState(null); 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, image: image || undefined }); }; return (
); } ``` ## Next.js ```tsx Text-to-Video theme={null} '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(null); const [prompt, setPrompt] = useState(''); const [isConnected, setIsConnected] = useState(false); const [isStreaming, setIsStreaming] = useState(false); useEffect(() => () => client.disconnect(), []); const handleConnect = async () => { const mediaStream = await client.connect(); if (videoRef.current) videoRef.current.srcObject = mediaStream; setIsConnected(true); }; const handleSend = async () => { const text = prompt; setPrompt(''); if (isStreaming) { await client.interact({ prompt: text }); } else { await client.startStream({ prompt: text }); setIsStreaming(true); } }; return (
); } ``` ```tsx Image-to-Video theme={null} '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(null); const [prompt, setPrompt] = useState(''); const [image, setImage] = useState(null); const [isConnected, setIsConnected] = useState(false); const [isStreaming, setIsStreaming] = useState(false); useEffect(() => () => client.disconnect(), []); const handleConnect = async () => { const mediaStream = await client.connect(); if (videoRef.current) videoRef.current.srcObject = mediaStream; setIsConnected(true); }; const handleSend = async () => { const text = prompt; setPrompt(''); if (isStreaming) { await client.interact({ prompt: text }); } else { await client.startStream({ prompt: text, image: image || undefined }); setIsStreaming(true); } }; return (
); } ``` ```tsx Text-to-Video theme={null} '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(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 (
); } ``` ```tsx Image-to-Video theme={null} '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(null); const [prompt, setPrompt] = useState(''); const [image, setImage] = useState(null); 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, image: image || undefined }); }; return (
); } ``` ```tsx Text-to-Video theme={null} 'use client'; import { useOdyssey } from '@odysseyml/odyssey/react'; import { useRef, useEffect, useState } from 'react'; export default function OdysseyDemo() { const videoRef = useRef(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(() => () => odyssey.disconnect(), []); const handleSend = () => { const text = prompt; setPrompt(''); isStreaming ? odyssey.interact({ prompt: text }) : odyssey.startStream({ prompt: text }); }; return (
); } ``` ```tsx Image-to-Video theme={null} 'use client'; import { useOdyssey } from '@odysseyml/odyssey/react'; import { useRef, useEffect, useState } from 'react'; export default function OdysseyDemo() { const videoRef = useRef(null); const [prompt, setPrompt] = useState(''); const [image, setImage] = useState(null); 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(() => () => odyssey.disconnect(), []); const handleSend = () => { const text = prompt; setPrompt(''); isStreaming ? odyssey.interact({ prompt: text }) : odyssey.startStream({ prompt: text, image: image || undefined }); }; return (
); } ``` Next.js App Router requires the `'use client'` directive for components using React hooks and browser APIs like video elements. ## Python ```python Text-to-Video theme={null} 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()) ``` ```python Image-to-Video theme={null} 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()) ``` ## Next Steps Get help and share what you're building.