Skip to main content
QwenCloud home page
Docs
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: Define a reusable World. Required parameters differ by mode:
  2. Poll the build status (every 3–5 seconds is recommended) until it reaches ready:
  3. Deliver credentials to the client: As described in Get Authentication Credentials, obtain the temporary API Key and the ticket, then deliver both to the client.

2. Real-time Experience (Client SDK)

The client SDK uses the temporary API Key and ticket delivered by your server to run the real-time experience. It handles the RTC connection, video playback, status polling, and interaction commands — you do not need to work with the underlying real-time protocol directly. A Travel (experience session) generally goes through the stages "initialize → prepare → running → (optionally pause/rewind) → end"; the exact status values are per-SDK — see the corresponding SDK API reference. The steps below describe generic actions. Method names differ slightly among the Web, Android, and iOS SDKs — check the corresponding SDK API reference for exact signatures and call ordering.
  1. Initialize the SDK: Inject the API Host and the model for your experience mode, then inject the temporary API Key via updateToken.
  2. Start the session: Start the Travel with a ticket; the SDK enters the room and establishes the RTC connection automatically. In Adventure mode, maxExperienceTimeSec is optional (60 / 90 / 120 seconds; default 60).
  3. Attach the video: Retrieve the video view from the SDK and place it in your layout. For Acting mode, set the container orientation according to the aspectRatio returned when entering the room (portrait 9:16 or landscape 16:9); the remote video is bound with clip-to-fill, so a mismatched orientation crops the picture rather than adding letterbox bars.
  4. Real-time interaction (capabilities differ by mode):
    • Adventure: Send directional / camera / action commands via sendCommand.
    • Directing: In the simple sub-mode, send text instructions via sendInstruct to drive the story. In the scriptlist sub-mode, the story is driven by a structured script; the script is edited on the server via HappyOyster-Directing-Update Script, and sendInstruct is not supported at the SDK layer.
    • Acting: Send text instructions via sendInstruct; sendCommand is not supported.
  5. Session control:
    • Pause / resume: Available only for Directing and Acting. Calling in Adventure is rejected by the SDK with 103003.
    • Rewind: Available only for Directing. Calling in Acting or Adventure is likewise rejected with 103003.
  6. End the session: End the Travel; the SDK disconnects RTC and releases resources automatically. Observe the session's terminal state and errors through the SDK's status and error events.

3. Retrieve Artifacts (Server Open API)

After the experience ends, your server calls the HappyOyster Open APIs to retrieve the composed video.
  1. Query artifacts: Poll with the primary API Key until composeStatus is ready. Choose the endpoint that matches your mode:
  2. Get the video: 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.
Integration Flow - QwenCloud