Skip to main content
Quick Start

Integration Flow

Your server prepares worlds and exports artifacts through the HappyOyster Open APIs; the client SDK handles the RTC connection and real-time interaction.

HappyOyster follows a server + client split: your server manages worlds and artifacts via the Open APIs, and the client SDK delivers the real-time experience. Before you start, complete Get Authentication Credentials.
  • Server-side Open APIs are split by experience mode into Adventure, Directing, and Acting. Choose the endpoints that match your mode.
  • A World and a Travel are strictly bound to the model that created them; cross-model access returns 403001 (world) or 404000 (travel).
  • The SDK is not responsible for creating or managing worlds; it only delivers the client-side real-time experience.

1. Prepare a World (Server Open API)

  1. Create a World, using the endpoint for your mode: Adventure-Create World / Directing-Create World / Acting-Create World.
  2. Poll the build status (every 3–5 seconds) until ready: Adventure-Query World Build Status / Directing-Query World Build Status / Acting-Query World Build Status.
  3. Exchange for a ticket: With the primary API Key, call Adventure-Get Travel Credential / Directing-Get Travel Credential / Acting-Get Travel Credential to obtain a one-time ticket.
  4. Deliver credentials to the client: Send the ticket together with the temporary API Key (used as the SDK's token) to the client.

2. Real-time Experience (Client SDK)

The SDK handles the RTC connection, video playback, and interaction commands.
  1. Initialize the SDK: initialize + updateToken — inject the API Host and the temporary API Key.
  2. Start the session: startTravel(ticket); the SDK enters the room and establishes the connection automatically.
  3. Attach the video: Add the view returned by attachVideo() to your layout. For Acting, set the container orientation according to the aspectRatio returned when entering the room.
  4. Real-time interaction:
    • Adventure: Call sendCommand to send directional / camera / action commands.
    • Directing: Call sendInstruct to send text instructions that drive the story.
    • Acting: Call sendInstruct to send text instructions.
  5. Session control:
    • Adventure: Pause and rewind are not supported.
    • Directing: Supports pause, rewind, and resume.
    • Acting: Supports pause and resume; rewind is not supported.
  6. End the session: endTravel releases RTC and resources.

3. Retrieve Artifacts (Server Open API)

After the Travel ends, poll with the primary API Key on Adventure-Query Travel Artifacts / Directing-Query Travel Artifacts / Acting-Query Travel Artifacts until composeStatus = ready. For external delivery, we recommend video.withInstructionAndWatermark (composed with instructions and watermark).

Next Steps

  • Download SDKs and Demos: SDK packages, integration guides, API references, and open-source demos for each platform.
API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
World models
Audio
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More