HappyOyster Web SDK API リファレンス - Alibaba Cloud Model Studio

HappyOysterEngine は Open Platform のホストとモデルを設定し、Model Studio 一時 API キートークンを更新し、Travel セッションを作成します。Travel は createTravel() によって返されるセッションオブジェクトで、travel.start() を呼び出した後にのみセッションへの参加と開始が行われます。adventure、directing、acting モードをサポートしています。

HappyOysterEngine は Open Platform ホストを設定し、Model Studio 一時 API キートークンを更新し、Travel セッションを作成します。

Travel は createTravel() によって返されるセッションオブジェクトです。セッションへの参加と開始は、travel.start() が呼び出された後にのみ行われます。

主要用語

用語	意味	備考
token	Model Studio 一時 API キートークン：ブラウザやモバイルアプリなどの信頼されていない環境から Model Studio サービスを呼び出す際は、永続的な API キーの露出を避けるため、安全なバックエンドを通じて一時的な API キーを生成してください。SDK はこのトークンを HTTP Bearer 認証情報として Open Platform に送信します。	認証情報の取得
ticket	HappyOyster ワールド Travel 認証情報：バックエンドが AK 認証（ゲートウェイヘッダー）を使用して認証情報 API を呼び出し、クライアントがルームに入るために使用する短命の Travel 認証情報（`ticket`）を取得します。API はワールドの所有権を検証しますが、実際の Travel レコードは作成しません。	認証情報の取得

概要

SDKは以下の主要オブジェクトを提供します：

HappyOysterEngine

API	説明
`new HappyOysterEngine(config)`	Engineインスタンスを作成します。
`updateToken(token)`	後続のOpen Platform APIリクエストで使用されるModel Studio一時APIキートークンを更新します。
`createTravel(config)`	Travelセッションを作成します。
`HappyOysterEngine.version`	現在のSDKバージョン。
`HappyOysterEngine.metadata`	現在のSDKパッケージ名、バージョン、およびパッケージチャネル。

Travel

API	説明
`start()`	現在のTravelセッションを開始します。
`on("statusChanged", handler)`	セッションステータスの変更を購読します。
`on("firstFrameGenerated", handler)`	最初のフレームURL通知を購読します。
`on("travelInfoReady", handler)`	Travel入場直後に利用可能になるセッションメタデータを購読します。
`onError(handler)`	セッションの実行時エラーを購読します。
`can(action)`	指定されたアクションを現在呼び出せるかどうかを確認します。
`getInfo()`	利用可能なセッションメタデータを取得します。利用可能になる前は `null` を返します。
`sendCommand(params)`	リアルタイム制御コマンドを送信します。
`sendInstruct(params)`	ディレクション指示またはプロンプトコンテンツを送信します。
`pause()`	現在のセッションを一時停止します。
`resume()`	一時停止中のセッションを再開します。
`rewind(params)`	ディレクションセッションを指定された時間に巻き戻します。
`end()`	現在のセッションを終了し、そのリソースを解放します。

その他のエクスポート

エクスポート	説明
`ErrorCode`	SDKによってエクスポートされるエラーコード定数オブジェクト。
`isSdkError(error)`	不明なエラーが標準SDKエラーかどうかを確認します。
型	`SDKConfig`、`Travel`、`StartTravelResult`、`AdventureCommand` などのパブリック型。

例

import { HappyOysterEngine, isSdkError } from '@happy-oyster/js-sdk'

const engine = new HappyOysterEngine({
  APIHost: 'open-platform.example.com',
  model: 'happyoyster-1.0-adventure', // Required; Adventure model shown as an example
  token: 'bailian-temporary-api-key-token',
  logLevel: 'warn',
  streamReadyTimeout: 15_000,
})

const videoElement = document.getElementById('player') as HTMLVideoElement
const travel = engine.createTravel({
  ticket: 'travel-ticket',
  videoElement,
  maxExperienceTimeSec: 90,
})

const unsubscribeStatus = travel.on('statusChanged', (status) => {
  console.log('Travel status:', status)
})

const unsubscribeFirstFrame = travel.on('firstFrameGenerated', (firstFrame) => {
  console.log('First frame URL:', firstFrame)
})

const unsubscribeInfo = travel.on('travelInfoReady', (info) => {
  console.log('Travel info is ready before RTC playback:', info)
})

const unsubscribeError = travel.onError((error) => {
  console.error('Travel error:', error)
})

try {
  const { encryptedTravelId, mode, creationModel, firstFrame, maxExperienceTimeSec, aspectRatio } = await travel.start()

  // Adventure (mode 1)
  await travel.sendCommand({
    translation: 'Front',
    rotation: 'Mouse_Left',
    interaction: 'Jump',
  })

  // Directing (mode 2) or Acting (mode 3; not scriptlist)
  await travel.sendInstruct({ content: 'Turn the camera toward the castle and have the protagonist start running' })

  await travel.pause()
  await travel.resume()
} catch (err) {
  if (isSdkError(err)) {
    console.error('SDK error:', err.code, err.message)
  } else {
    console.error('Unexpected error:', err)
  }
} finally {
  unsubscribeStatus()
  unsubscribeFirstFrame()
  unsubscribeInfo()
  unsubscribeError()
  await travel.end()
}

engine.updateToken('new-bailian-temporary-api-key-token')

`HappyOysterEngine`

HappyOysterEngine は Web SDK のエントリーポイントです。Open Platform ホストを設定し、後続のリクエストで使用される Model Studio 一時 API キートークンを管理し、Travel セッションを作成します。

注記Engine インスタンスは、現在一度に 1 つのアクティブな Travel のみを管理します。新しいセッションを開始する前に、現在の Travel を終了してください。

コンストラクタまたは updateToken() を通じてトークンが設定された後、SDK は内部で Feature Gate 設定を取得します。これにより、プラットフォームはリモートで SDK を無効化したり、古いバージョンにアップグレードを要求したりできます。リクエストが失敗した場合、SDK はフェイルオープンとなり、通常の体験をブロックしません。

API	説明
`new HappyOysterEngine(config)`	必須のAPIホストとモデル、およびオプションのトークンとログレベルを指定してEngineインスタンスを作成します。
`updateToken(token)`	後続のOpen Platformリクエストで使用されるModel Studio一時APIキートークンを更新します。
`createTravel(config)`	まだ開始されていないTravelセッションを作成します。

`new HappyOysterEngine`

HappyOysterEngineインスタンスを作成します。

シグネチャ

new HappyOysterEngine(config: SDKConfig)

パラメータ

`SDKConfig`

フィールド	タイプ	必須	説明
`APIHost`	`string`	はい	Open Platform API ホスト。`open-platform.example.com` のようなベアホストである必要があり、`https://`、スキーム、またはパスを含めることはできません。
`model`	`string`	はい	使用する Open Platform モデルの識別子です。必須で、デフォルト値はありません。この Engine で固定され、そのすべての Travel で共有されます。
`token`	`string`	いいえ	構築時に設定される Model Studio 一時 API キートークンです。後から `updateToken()` で設定することもできます。
`logLevel`	`LogLevel`	いいえ	SDKログレベル。デフォルトは `none` です。
`streamReadyTimeout`	`number`	いいえ	`<video>` が再生可能、停止、または再開状態になるまでの待機タイムアウト（ミリ秒単位）。デフォルトは `15000` です。

modelをモデル識別子（Adventureモデルであるhappyoyster-1.0-adventureなど）に設定します。対象のサービス環境に対応するモデル識別子を使用してください。SDKは体験用modeからモデルを選択したり、ticketからモデルを推測したりすることはありません。

Engine には固定の APIHost + model があります。同じサービスとモデルを対象とする連続した Travel には再利用してください。いずれかの値を切り替える前に、アクティブな Travel を終了し、新しいターゲット用に設定された Engine を使用してください。ワールドの作成とそのチケットの発行は、同じサービスターゲットに対して行ってください。

戻り値

HappyOysterEngineインスタンスを返します。

エラー

config が欠落している場合、または APIHost、model、token、logLevel、streamReadyTimeout の型や値が無効な場合、コード ErrorCode.INVALID_ARGUMENT (10010001) の SdkError が同期的にスローされます。完全な URL、空の文字列、またはパスを含む値を APIHost として渡すことは無効です。

model は必須であり、トリム後に空でない文字列である必要があります。null、文字列以外の値、および空白のみの文字列は無効です。これを省略するか undefined を渡しても引数エラーが発生します。SDK にはデフォルトのモデルがありません。

`HappyOysterEngine.updateToken`

後続のOpen Platform APIリクエストで使用されるModel Studio一時APIキートークンを更新します。

シグネチャ

updateToken(token: string): void

パラメータ

フィールド	タイプ	必須	説明
`token`	`string`	はい	Model Studioの一時APIキートークン。空文字列を渡すと現在のトークンがクリアされます。

戻り値

何も返しません。

エラー

token が文字列でない場合、コード ErrorCode.INVALID_ARGUMENT (10010001) の SdkError が同期的にスローされます。

`HappyOysterEngine.createTravel`

開始せずにTravelセッションインスタンスを作成します。

シグネチャ

createTravel(config: CreateTravelConfig): Travel

パラメータ

`CreateTravelConfig`

フィールド	タイプ	必須	説明
`ticket`	`string`	はい	後でTravelを開始するために使用するチケット。
`videoElement`	`HTMLVideoElement`	はい	セッションビデオのレンダリングに使用される `<video>` 要素。Travel作成時に指定する必要があります。
`maxExperienceTimeSec`	`60 \| 90 \| 120`	いいえ	Adventure の最大体験時間（秒単位）。Directing および Acting セッションではこのフィールドは無視されます。省略した場合、サーバーのデフォルトが適用されます。

戻り値

作成済みだがまだ開始されていない Travel セッションを返します。その後、呼び出し元は await travel.start() を実行してセッションに参加し、ビデオが再生可能になるまで待機する必要があります。

各 HappyOysterEngine インスタンスは、一度に 1 つのアクティブな Travel のみを持つことができます。別の Travel を作成する前に await travel.end() を呼び出してください。

エラー

createTravel() は以下のケースで同期的に SdkError をスローします：

ErrorCode	説明
`10010001`	`config`、`ticket`、`videoElement`、または `maxExperienceTimeSec` が無効です
`10010101`	Travelは既にアクティブです。先に `travel.end()` を呼び出してください

起動エラーは travel.start() によって公開されます。

`Travel`

Travel は HappyOysterEngine.createTravel() によって作成されたセッションを表します。初期状態では非アクティブです。travel.start() が呼び出された後、SDK はセッションに参加し、ビデオが再生可能になるまで待機します。

Travel は、セッションの開始、一時停止、再開、巻き戻し、終了、リアルタイム制御とプロンプトの送信、およびステータス変更とランタイムエラーのサブスクライブをサポートしています。

メソッド

メソッド	説明
`start()`	現在のTravelセッションを開始します。
`on("statusChanged", handler)`	セッションステータスの変更を購読します。
`on("firstFrameGenerated", handler)`	最初のフレームURL通知を購読します。
`on("travelInfoReady", handler)`	Travel入場直後に利用可能になるセッションメタデータを購読します。
`onError(handler)`	セッションの実行時エラーを購読します。
`can(action)`	指定されたアクションを現在呼び出せるかどうかを確認します。
`getInfo()`	利用可能なセッションメタデータを取得します。利用可能になる前は `null` を返します。
`sendCommand(params)`	リアルタイム制御コマンドを送信します。
`sendInstruct(params)`	ディレクション指示またはプロンプトコンテンツを送信します。
`pause()`	現在のセッションを一時停止します。
`resume()`	一時停止中のセッションを再開します。
`rewind(params)`	現在のセッションを指定された時間に巻き戻します。
`end()`	現在のセッションを終了し、そのリソースを解放します。

ステータス

ステータス	説明
`idle`	セッションが開始されていません。
`prepare`	セッションは開始中で、ビデオが再生可能になるのを待っています。
`running`	セッションは実行中です。
`paused`	セッションは一時停止中で、再開または巻き戻しが可能です。
`completed`	セッションは正常に終了し、そのリソースは解放されました。

イベント

イベントの購読には travel.on(event, handler) を使用します。このメソッドは購読解除関数を返します。

イベント	コールバック	説明
`statusChanged`	`(status: TravelStatus) => void`	セッションステータスが変更されました。
`firstFrameGenerated`	`(firstFrame: string) => void`	Open Platform が空でない最初のフレーム URL を返した際に `start()` 中に発火します。`start()` が解決してビデオが再生可能になる前のタイミングです。
`travelInfoReady`	`(info: TravelInfo) => void`	enter-travel が戻った後、RTC が接続される前に発火します。`getInfo()` も同じデータを返します。最初のフレームが存在する場合は、`firstFrameGenerated` が続いて発火します。
`error`	`(error: unknown) => void`	セッションの実行時エラー。

`Travel.can`

現在のステータスとセッション機能に対してアクションが利用可能かどうかを確認します。

シグネチャ

can(action: TravelAction): boolean

パラメータ

フィールド	タイプ	必須	説明
`action`	`TravelAction`	はい	確認対象のアクション：`start` / `sendCommand` / `sendInstruct` / `pause` / `resume` / `rewind` / `end`。

戻り値

boolean を返します。true はアクションが現在利用可能であることを意味し、false は現在のステータス、モード、またはセッション機能がその前提条件を満たしていないことを意味します。

利用条件

action	利用条件
`start`	Travelがまだ `idle` で、クローズされておらず、一度も開始されていない場合。
`sendCommand`	`running` であり、TravelモードがAdventure（`1`）に設定されている場合。
`sendInstruct`	`running` または `paused` で、モードが Directing (`2`) または Acting (`3`) に設定されており、かつ `scriptlist` ではない状態。
`pause`	`running` であり、かつ現在のセッションが一時停止をサポートしている場合。
`resume`	`paused` であり、かつ現在のセッションが再開をサポートしている場合。
`rewind`	巻き戻しをサポートするディレクションセッションにおける `paused` ステータス。アクトではサポートされていません。
`end`	Travelがクローズされていません。

エラー

このメソッドはビジネスエラーをスローしません。不明なアクションの場合は false を返します。

`Travel.start`

現在のTravelセッションを開始します。

シグネチャ

start(): Promise<StartTravelResult>

パラメータ

パラメータはありません。

戻り値

Promise<StartTravelResult> を返し、これはセッションが開始されビデオが再生可能になった後に解決されます。

enter-travel が戻った後、SDK は RTC に接続する前に travelInfoReady を発火します。遅れてサブスクライブする場合は travel.getInfo() を呼び出すことができますが、メタデータが利用可能になる前は null を返します。レスポンスに空でない firstFrame が含まれている場合でも、firstFrameGenerated は引き続き発火します。

`StartTravelResult`

フィールド	タイプ	説明
`encryptedTravelId`	`string`	現在のTravelセッションID。
`mode`	`number`	セッションモード：`1` = Adventure（ワールド探索）、`2` = Directing（リアルタイム演出）、`3` = Acting。
`creationModel`	`string`	ワールド作成モデル。一般的な値は `simple` および `scriptlist` です。
`firstFrame`	`string \| null`	最初のフレーム画像URL。サーバーから返されない場合は `null` になります。
`maxExperienceTimeSec`	`60 \| 90 \| 120 \| null`	Adventure の最大体験時間（秒単位）。Directing および Acting セッションの場合、またはサーバーがこのフィールドを返さない場合は `null` となります。
`aspectRatio`	`"9:16" \| "16:9" \| null`	アクトのアスペクト比。他のモードの場合やサーバーから返されない場合は `null` になります。

エラー

以下のケースでは start() が reject され、error イベントが発火します。エラーを確認するには isSdkError(err) を使用し、err.code と err.message を読み取ってください。

ErrorCode	説明
`10010002`	SDK機能が無効になっています（`SDK_FEATURE_DISABLED`）
`10020101`	開始できません：現在のステータスでは許可されていないか、Open Platform が設定されていないか、セッションへの参加に失敗しました
`10020102`	開始できません：サーバーから返されたセッション設定が不完全です
`10020103`	開始できません：ビデオストリーム接続に失敗したか、SDK機能フラグのリクエストに失敗しました
`10020104`	開始できません：ビデオストリームの待機中にタイムアウトしました（`streamReadyTimeout` とサーバーの `noStreamAutoEndTimeoutSec` の大きい方の値を使用）
`10020105`	開始できません：ビデオが再生可能になるまでの待機中にタイムアウトしました（`streamReadyTimeout` により制御、デフォルト：15 秒）
`10000001`–`10000012`	Open Platformのパラメータ、リソース、またはサーバーエラー

`Travel.on("statusChanged")`

セッションステータスの変更を購読します。

シグネチャ

on("statusChanged", handler: (status: TravelStatus) => void): () => void

パラメータ

フィールド	タイプ	必須	説明
`handler`	`(status: TravelStatus) => void`	はい	ステータス変更時に呼び出されるコールバックです。

戻り値

購読解除関数を返します。TravelStatus は idle / prepare / running / paused / completed のいずれかです。

エラー

このメソッドはビジネスエラーをスローしません。

`Travel.on("firstFrameGenerated")`

最初のフレームURL通知を購読します。

シグネチャ

on("firstFrameGenerated", handler: (firstFrame: string) => void): () => void

パラメータ

フィールド	タイプ	必須	説明
`handler`	`(firstFrame: string) => void`	はい	最初のフレームURLが利用可能になったときに呼び出されるコールバックです。

戻り値

購読解除関数を返します。

動作

travel.start() 中にのみ発火します。SDK が Open Platform の enter-travel を呼び出し、空でない firstFrame を受信した後、通常は statusChanged("prepare") の後ですが start() が解決してビデオが再生可能になる前に、イベントが即座に発火します。レスポンスに最初のフレーム URL が含まれていない場合、イベントは発火しません。

エラー

このメソッドはビジネスエラーをスローしません。

`Travel.onError`

セッションの実行時エラーを購読します。

シグネチャ

onError(handler: (error: unknown) => void): () => void

パラメータ

フィールド	タイプ	必須	説明
`handler`	`(error: unknown) => void`	はい	ランタイムエラー発生時に呼び出されるコールバックです。

戻り値

購読解除関数を返します。isSdkError を使用してエラーオブジェクトを SdkError に絞り込むことができます。

エラー

このメソッドはビジネスエラーをスローしません。

`Travel.sendCommand`

リアルタイム制御コマンドを送信します。

シグネチャ

sendCommand(params: AdventureCommand): Promise<void>

パラメータ

`AdventureCommand`

フィールド	タイプ	必須	説明
`translation`	`string`	いいえ	移動方向。省略時のデフォルトは `None` です。
`rotation`	`string`	いいえ	視点回転。省略時のデフォルトは `None` です。
`interaction`	`string`	いいえ	インタラクションアクション。省略時のデフォルトは `None` です。

制御コマンドリファレンス

`translation` — 移動方向

キャラクターの移動を表し、8方向とその組み合わせをサポートします。

値	方向
`"Front"`	前進
`"Back"`	後退
`"Left"`	左
`"Right"`	右
`"Front_Left"`	左前
`"Front_Right"`	右前
`"Back_Left"`	左後
`"Back_Right"`	右後
`"None"`	静止

`rotation` — 視点回転

マウス操作による8方向の視点回転をシミュレートします。

値	方向
`"Mouse_Up"`	上
`"Mouse_Down"`	下
`"Mouse_Left"`	左
`"Mouse_Right"`	右
`"Mouse_Up_Left"`	左上
`"Mouse_Up_Right"`	右上
`"Mouse_Down_Left"`	左下
`"Mouse_Down_Right"`	右下
`"None"`	None

`interaction` — インタラクションアクション

値	操作
`"Jump"`	ジャンプ
`"Attack"`	攻撃
`"Crouch"`	しゃがむ
`"Sprint"`	ダッシュ
`"None"`	None

戻り値

コマンド送信後に解決される Promise<void> を返します。

エラー

sendCommand() は以下のケースで reject されます：

ErrorCode	説明
`10010001`	`params` または移動、回転、インタラクションのパラメータが無効です
`10020501`	現在のステータスまたはセッションモードではコマンドが許可されていないか、ビデオストリームコマンドが失敗しました

`Travel.sendInstruct`

ディレクション指示またはプロンプトコンテンツを送信します。

シグネチャ

sendInstruct(params: InstructData): Promise<void>

パラメータ

`InstructData`

フィールド	タイプ	必須	説明
`content`	`string`	はい	送信するプロンプトの内容。

戻り値

Open Platformが指示を受信して処理した後に解決される Promise<void> を返します。

エラー

sendInstruct() は以下のケースで reject され、error イベントを発行します：

ErrorCode	説明
`10020101`	セッションが開始されていません
`10020601`	ディレクション指示の送信に失敗しました
`10000001`–`10000012`	Open Platformのパラメータ、リソース、またはサーバーエラー

`Travel.pause`

現在のセッションを一時停止します。

シグネチャ

pause(): Promise<void>

パラメータ

パラメータはありません。

戻り値

ビデオ再生停止後に解決される Promise<void> を返します。

エラー

pause() は以下のケースで reject されます：

ErrorCode	説明
`10020201`	現在のステータス、セッションモード、またはセッション機能では一時停止が許可されていないか、一時停止リクエストが失敗しました
`10020202`	バックエンドがビデオストリームの一時停止を報告するのを待っている間にタイムアウトしました（15秒）
`10000001`–`10000012`	Open Platformのパラメータ、リソース、またはサーバーエラー

`Travel.resume`

一時停止中のセッションを再開します。

シグネチャ

resume(): Promise<void>

パラメータ

パラメータはありません。

戻り値

ビデオが再び再生可能になった後に解決される Promise<void> を返します。

エラー

resume() は以下のケースで reject されます：

ErrorCode	説明
`10020301`	現在のステータス、セッションモード、またはセッション機能では再開が許可されていないか、再開リクエストが失敗しました
`10020302`	ビデオが再び再生可能になるのを待っている間にタイムアウトしました（15秒）
`10000001`–`10000012`	Open Platformのパラメータ、リソース、またはサーバーエラー

`Travel.rewind`

現在のセッションを指定された時間に巻き戻します。

シグネチャ

rewind(params: RewindTravelParams): Promise<RewindTravelResult>

パラメータ

`RewindTravelParams`

フィールド	タイプ	必須	説明
`rewindToSec`	`number`	はい	ターゲット時間（秒単位）。4 の倍数のみがサポートされています（例：`4`、`8`、または `12`）。サーバーは他の値を切り捨てます（例：`7` は `4` になります）。

戻り値

巻き戻しが完了して再生が再開された後に解決される Promise<RewindTravelResult> を返します。

`RewindTravelResult`

フィールド	タイプ	説明
`resumedAtSec`	`number`	サーバーが再生を再開した実際の時刻（秒単位）。

エラー

rewind() は以下のケースで reject され、error イベントを発行します：

ErrorCode	説明
`10020101`	セッションが開始されていません
`10020401`	巻き戻しできません：先にセッションを一時停止してビデオ再生を停止する必要があります。または、巻き戻しリクエストもしくは RTC 再接続に失敗しました
`10020402`	巻き戻し後にビデオが再開するのを待っている間にタイムアウトしました（15秒）
`10000001`–`10000012`	Open Platformのパラメータ、リソース、またはサーバーエラー

`Travel.end`

現在のセッションを終了し、そのリソースを解放します。

シグネチャ

end(): Promise<void>

パラメータ

パラメータはありません。

戻り値

クリーンアップ完了後に解決される Promise<void> を返します。

エラー

クリーンアップエラーは呼び出し元にスローされません。end() はリソース解放のために最善の努力を行います。

エラー処理

SDK は Promise の reject または error イベントを通じてランタイムエラーを公開します。エラーは SdkError オブジェクトです。isSdkError(err) を使用して err.code と err.message を読み取ってください。

認識された Open Platform エラーは 10000001–10000012 の範囲にマッピングされ、err.message にはプラットフォームのメッセージが含まれます。メソッド固有のコードについては、各 Travel API の Errors セクションを参照してください。

ErrorCodeリファレンス

エラーコード範囲：

100000xx：マップされたOpen Platformエラー
1001xxxx：Engineクライアントエラー
1002xxxx：Travelクライアントエラー

code	name	説明
`10000001`	`OPEN_PLATFORM_PARAM_INVALID`	無効なリクエストパラメータ（Open Platformから返される）
`10000002`	`OPEN_PLATFORM_RESOURCE_NOT_FOUND`	リソースが見つかりません（Travelが存在しない、所有権がない、別のワークスペースにある、またはアーティファクトの準備ができていない）
`10000003`	`OPEN_PLATFORM_WORLD_NOT_OWNED`	ワールドが存在しない、削除された、または現在の開発者に属していません
`10000004`	`OPEN_PLATFORM_SYSTEM_ERROR`	システムエラー
`10000005`	`OPEN_PLATFORM_TICKET_INVALID`	チケットが無効または期限切れです
`10000006`	`OPEN_PLATFORM_TICKET_USED`	チケットは既に使用されています（ワンタイムクレデンシャル）
`10000007`	`OPEN_PLATFORM_WORLD_NOT_READY`	ワールドの準備ができていないため、入場できません
`10000008`	`OPEN_PLATFORM_INFERENCE_ALLOCATE_FAILED`	推論リソースの割り当てに失敗しました（キャパシティ不足、ストリーム作成失敗、セッション初期化失敗など）
`10000009`	`OPEN_PLATFORM_MAIN_API_KEY_REQUIRED`	このAPIはプライマリAPIキーのみを受け付けます（一時APIキーはサポートされていません）
`10000010`	`OPEN_PLATFORM_CONTENT_MODERATION`	コンテンツモデレーションにより入力が拒否されました
`10000011`	`OPEN_PLATFORM_CONTENT_COPYRIGHT`	入力画像が著作権またはIPポリシーに違反しています
`10000012`	`OPEN_PLATFORM_STATE_CONFLICT`	リクエストが現在のリソース状態と競合しています
`10010001`	`INVALID_ARGUMENT`	SDKクライアントの引数検証に失敗しました（Open Platformからはマッピングされません）
`10010002`	`SDK_FEATURE_DISABLED`	SDK機能が無効になっています
`10010101`	`ACTIVE_TRAVEL_EXISTS`	Travelはすでにアクティブです
`10020001`	`STREAM_DISCONNECTED_WHILE_PLAYING`	再生中にビデオストリームが切断されました
`10020101`	`START_REQUEST_FAILED`	セッション開始リクエスト失敗
`10020102`	`START_RTC_CONFIG_MISSING`	起動時にビデオストリーム設定が見つかりません
`10020103`	`START_JOIN_CHANNEL_FAILED`	ビデオストリーム接続失敗
`10020104`	`START_REMOTE_USER_TIMEOUT`	ビデオストリームの待機中にタイムアウトしました
`10020105`	`START_STREAM_TIMEOUT`	ビデオが再生可能になるのを待っている間にタイムアウトしました
`10020201`	`PAUSE_REQUEST_FAILED`	一時停止リクエスト失敗
`10020202`	`PAUSE_STREAM_TIMEOUT`	ビデオの一時停止待機中にタイムアウトしました
`10020301`	`RESUME_REQUEST_FAILED`	再開リクエスト失敗
`10020302`	`RESUME_STREAM_TIMEOUT`	ビデオの再開待機中にタイムアウトしました
`10020401`	`REWIND_REQUEST_FAILED`	巻き戻しリクエスト失敗
`10020402`	`REWIND_STREAM_TIMEOUT`	巻き戻し後にビデオが再開するのを待っている間にタイムアウトしました
`10020501`	`SEND_COMMAND_FAILED`	リアルタイム制御コマンドの送信に失敗しました
`10020601`	`INSTRUCT_REQUEST_FAILED`	ディレクション指示の送信に失敗しました
`10020701`	`END_REQUEST_FAILED`	セッション終了リクエスト失敗

その他のエクスポート

ランタイムエクスポート

エクスポート	タイプ	説明
`HappyOysterEngine`	`class`	Open Platformの設定、トークンの更新、およびTravelセッションの作成を行うSDKクライアント。
`HappyOysterEngine.version`	`string`	現在のSDKバージョン。
`HappyOysterEngine.metadata`	`SDKMetadata`	現在のSDKパッケージ名、バージョン、およびパッケージチャネル。
`ErrorCode`	`const`	SDKによってエクスポートされるエラーコード定数オブジェクト。
`isSdkError`	`function`	不明なエラーが標準SDKエラーかどうかを確認します。

`ErrorCode`

SDK からエクスポートされるエラーコード定数オブジェクトです。アプリケーションコード全体に数値リテラルを散在させるのではなく、SdkError.code と比較してください。

import { ErrorCode } from '@happy-oyster/js-sdk'

`isSdkError`

未知のエラーが標準的な SDK エラーかどうかを確認します。これが true を返す場合、TypeScript はエラーを SdkError に絞り込み、code と message への安全なアクセスを可能にします。

isSdkError(error: unknown): error is SdkError

try {
  await travel.start()
} catch (err) {
  if (isSdkError(err) && err.code === ErrorCode.OPEN_PLATFORM_TICKET_INVALID) {
    // Request a new Travel ticket, then create a new Travel.
  }
}

パブリック型

以下の型はパッケージのエントリーポイントからエクスポートされており、@happy-oyster/js-sdk から直接インポートできます。これらは TypeScript のコンパイル時にのみ存在し、ランタイムコードは生成しません。

タイプ	説明
`SDKConfig`	`HappyOysterEngine` コンストラクタのパラメータ型。
`LogLevel`	SDK ログレベル：`verbose` / `debug` / `info` / `warn` / `error` / `none`。
`SDKMetadata`	SDKパッケージメタデータ：`version`、`packageName`、`packageChannel`。
`SDKPackageChannel`	SDKパッケージチャネル：`internal` / `public` / `unknown`。
`CreateTravelConfig`	`createTravel(config)` のパラメータ型。
`StartTravelResult`	Promise解決時に返される `start()` セッションメタデータ。
`TravelInfo`	`travelInfoReady`、`getInfo()`、および `StartTravelResult` で使用されるセッションメタデータ。
`TravelAspectRatio`	アクトのアスペクト比：`"9:16"` / `"16:9"`。
`Travel`	メソッドによって返される `createTravel()` パブリックセッションコントラクト。
`TravelStatus`	ローカル SDK セッションステータス：`idle` / `prepare` / `running` / `paused` / `completed`。
`TravelAction`	`can(action)` でサポートされるアクション名。
`AdventureCommand`	`sendCommand(params)` のパラメータ型。
`InstructData`	`sendInstruct(params)` のパラメータ型。
`RewindTravelParams`	`rewind(params)` のパラメータ型。
`RewindTravelResult`	Promise解決時に返される `rewind(params)` データ。
`SDKError`	`code` と `message` を含むSDKエラー構造体。
`SdkError`	ランタイム `Error` と `SDKError` を組み合わせたエラー型。
`ErrorCodeValue`	`ErrorCode` オブジェクト内のすべてのエラーコード値のユニオン型。

主要用語

概要

HappyOysterEngine

Travel

その他のエクスポート

例

HappyOysterEngine

new HappyOysterEngine

シグネチャ

パラメータ

SDKConfig

戻り値

エラー

HappyOysterEngine.updateToken

シグネチャ

パラメータ

戻り値

エラー

HappyOysterEngine.createTravel

シグネチャ

パラメータ

CreateTravelConfig

戻り値

エラー

Travel

メソッド

ステータス

イベント

Travel.can

シグネチャ

パラメータ

戻り値

利用条件

エラー

Travel.start

シグネチャ

パラメータ

戻り値

StartTravelResult

エラー

Travel.on("statusChanged")

シグネチャ

パラメータ

戻り値

エラー

Travel.on("firstFrameGenerated")

シグネチャ

パラメータ

戻り値

動作

エラー

Travel.onError

シグネチャ

パラメータ

戻り値

エラー

Travel.sendCommand

シグネチャ

パラメータ

AdventureCommand

制御コマンドリファレンス

translation — 移動方向

rotation — 視点回転

interaction — インタラクションアクション

戻り値

エラー

Travel.sendInstruct

シグネチャ

パラメータ

InstructData

戻り値

エラー

Travel.pause

シグネチャ

パラメータ

戻り値

エラー

Travel.resume

シグネチャ

パラメータ

`HappyOysterEngine`

`new HappyOysterEngine`

`SDKConfig`

`HappyOysterEngine.updateToken`

`HappyOysterEngine.createTravel`

`CreateTravelConfig`

`Travel`

`Travel.can`

`Travel.start`

`StartTravelResult`

`Travel.on("statusChanged")`

`Travel.on("firstFrameGenerated")`

`Travel.onError`

`Travel.sendCommand`

`AdventureCommand`

`translation` — 移動方向

`rotation` — 視点回転

`interaction` — インタラクションアクション

`Travel.sendInstruct`

`InstructData`

`Travel.pause`

`Travel.resume`

`Travel.rewind`

`RewindTravelParams`

`RewindTravelResult`

`Travel.end`

`ErrorCode`

`isSdkError`