HappyOyster iOS SDK API参考

import HappyOysterSDK

// 1) 初始化（App 启动后尽早，createTravel 前一次）
let engine = HappyOysterEngine.shared
engine.initialize(config: OysterConfig(
    apiHost: "maas.qianwenaiapi.com",// 网关地址获取参考千问AI平台文档
    model: "happyoyster-1.0-adventure"                  // 已开通的模型名（含版本），必填；取值见 HappyOyster 系列模型文档
))

// 2)（可选）接管日志：设置等级 + 自定义打印
OysterLog.setMinimumLevel(.info)
OysterLog.setHandler { level, tag, message in
    print("[Oyster][\(level)][\(tag)] \(message)")
}

// 3) 注入 HTTP 鉴权 token（千问AI平台临时 API Key，由你的服务端下发）
engine.updateToken(temporaryApiKey)

// 4) 用一次性 ticket 创建会话句柄（尚未建连）
let travel = try engine.createTravel(ticket: ticket)

Task { @MainActor in
    // 5) 挂载视频（UIKit；SwiftUI 用 OysterVideoView(travel:)）
    containerView.addSubview(travel.videoView)

    // 6) start 前就订阅事件，避免漏掉早期状态
    let eventTask = Task {
        for await event in travel.events {
            switch event {
            case .statusChanged(let status): render(status)   // 见"事件与状态"章节
            case .error(let error):          handle(error)     // 见"错误码"章节 error.code / error.kind
            }
        }
    }

    do {
        // 7) 建连播放
        let data = try await travel.start()

        // 8) 按模式互动：adventure 走操控指令，directing / acting 走文本指令
        if data.mode == .adventure {
            travel.sendCommand(OysterAdventureCommand(translation: .front))
        } else {
            _ = try await travel.sendInstruct(content: "突然下起了大雨")
        }
    } catch let error as OysterSDKError {
        handle(error)
    }

    // 9) 任意退出路径都收口到一次 end()
    _ = try? await travel.end()
    eventTask.cancel()
}

// 退出 SDK / 切换网关：await engine.cleanup()

# HappyOysterSDK / AliVCSDK_ARTC 均发布在 CocoaPods 公开源。
pod 'HappyOysterSDK', '1.0.3'              # 聚合入口（Core + World）
pod 'HappyOysterSDK/UI', '1.0.3'           # 可选：默认 UI 组件（视频视图、操控 HUD）
pod 'HappyOysterSDK/StreamAliRTC', '1.0.3' # 视频流 + AliRTC 引擎适配器（已依赖 Stream）

# RTC 厂商二进制：SDK 弱引用、不随 SDK 分发，由集成方自行引入。
pod 'AliVCSDK_ARTC', '7.11.0'

@MainActor @available(iOS 15.0, *)
public final class HappyOysterEngine {
    public static let shared: HappyOysterEngine            // 进程级唯一实例
    public static let version: String                      // 当前 SDK 版本号

    @discardableResult
    public func initialize(config: OysterConfig) -> Bool   // 初始化（createTravel 前一次）
    public func updateToken(_ token: String)               // 注入/更新 HTTP 鉴权 token
    public func createTravel(ticket: String) throws -> OysterTravel  // 用一次性凭证创建会话句柄
    public func cleanup() async                            // 释放资源（可再 initialize）
}

@discardableResult
public func initialize(config: OysterConfig) -> Bool

public func updateToken(_ token: String)

public func createTravel(ticket: String) throws -> OysterTravel

public func cleanup() async

@MainActor @available(iOS 15.0, *)
public final class OysterTravel: ObservableObject {
    @Published public private(set) var status: OysterTravelStatus   // 当前对外状态（可观察）
    public var isEnded: Bool { get }                                // 是否已到达终态（同步可读）
    public var videoView: UIView { get }                            // UIKit 播放视图；SwiftUI 用 OysterVideoView(travel:)
    public var events: AsyncStream<OysterTravelEvent> { get }       // 状态变更 + 错误，多订阅

    @discardableResult public func start() async throws -> OysterStartTravelData   // 建连播放
    @discardableResult public func start(maxExperienceTimeSec: Int?) async throws -> OysterStartTravelData  // 建连播放 + 请求最大体验时长（仅世界探索模式）
    @discardableResult public func pause() async throws -> OysterTravelStateData   // 暂停（directing / acting）
    @discardableResult public func resume() async throws -> OysterTravelStateData  // 恢复
    @discardableResult public func rewind(toSec: TimeInterval) async throws -> OysterRewindTravelData  // 回溯（仅 paused）
    @discardableResult public func end() async throws -> OysterEndTravelData       // 结束（幂等，务必调用）
    @discardableResult public func sendInstruct(content: String) async throws -> OysterSendInstructData  // 实时导演模式文本指令

    public func sendCommand(_ command: OysterAdventureCommand)      // 世界探索模式操控（fire-and-forget）
    public func flushCommands()                                     // 松键时补发最后一帧
    public func pauseLocalAudioCapture() async                      // 临时让出麦克风
    public func resumeLocalAudioCapture() async                     // 恢复麦克风占用
}

public var videoView: UIView { get }

@Published public private(set) var status: OysterTravelStatus
public var isEnded: Bool { get }
public var events: AsyncStream<OysterTravelEvent> { get }

@discardableResult public func start() async throws -> OysterStartTravelData
@discardableResult public func start(maxExperienceTimeSec: Int?) async throws -> OysterStartTravelData

@discardableResult public func pause() async throws -> OysterTravelStateData
@discardableResult public func resume() async throws -> OysterTravelStateData

@discardableResult public func rewind(toSec: TimeInterval) async throws -> OysterRewindTravelData

@discardableResult public func end() async throws -> OysterEndTravelData

@discardableResult public func sendInstruct(content: String) async throws -> OysterSendInstructData

public func sendCommand(_ command: OysterAdventureCommand)
public func flushCommands()

public func pauseLocalAudioCapture() async
public func resumeLocalAudioCapture() async

var events: AsyncStream<OysterTravelEvent> { get }

@available(iOS 15.0, *)
public enum OysterTravelEvent {
    case statusChanged(OysterTravelStatus)
    // SDK 内部流程出错，例如内部接口请求出错、推流出错，注意这里必须判断 token 过期并重新请求 token
    case error(OysterSDKError)
}

let task = Task {
    for await event in travel.events {
        switch event {
        case .statusChanged(let status): render(status)   // 见下表
        case .error(let error):          handle(error)     // error.code / error.kind，见"错误码"章节
        }
    }
}
// 结束时：task.cancel()

// 配置
public struct OysterConfig: Sendable {
    public let apiHost: String             // 千问AI平台网关地址（非业务 Server），必填、由宿主显式传入
    public let model: String               // 模型名含版本（如 "happyoyster-1.0-adventure"），必填、无默认值
    public let logLevel: OysterLogLevel?   // .debug/.info/.warning/.error；nil 时默认 .warning
    public let callbackTimeoutMs: Int      // 全局回调超时，默认 30000；超时按 105005 透出
    public init(apiHost: String, model: String, logLevel: OysterLogLevel? = nil, callbackTimeoutMs: Int = 30_000)
}

public enum OysterLogLevel: Int, Comparable, CaseIterable, Sendable {
    case debug, info, warning, error
}

// 对外会话状态（见"事件与状态"章节）
public enum OysterTravelStatus: String, Equatable, Sendable, CustomStringConvertible {
    case idle      // create 后、start 前
    case prepare   // 建连 / 重连中
    case running   // 流已就绪、可交互
    case pausing   // 暂停已受理、等待服务端确认
    case paused    // 已暂停（确认）
    case ended     // 终态：主动 end 或服务端结束
    case failed    // 终态：失败
}

// 开放字符串值（保留未知值，便于服务端扩展；编解码为裸 JSON 字符串 "running"）
public struct OysterRawValue: RawRepresentable, Equatable, Hashable, Codable, Sendable {
    public let rawValue: String
    public init(rawValue: String) { self.rawValue = rawValue }
}
public typealias OysterModeValue = OysterRawValue
public extension OysterModeValue {
    static let adventure = OysterModeValue(rawValue: "adventure")
    static let directing  = OysterModeValue(rawValue: "directing")
    static let acting     = OysterModeValue(rawValue: "acting")
}

// start() 返回（SDK 出参，非 Codable）
public struct OysterStartTravelData: Equatable, Sendable {
    public let encryptedTravelId: String  // 本次体验标识
    public let encryptedWorldId: String
    public let mode: OysterModeValue       // adventure / directing / acting
    public let playUrl: String?            // 当前服务端固定返回 null
    public let firstFrame: String?         // 首帧图地址，可能为 null（异步产生）
    public let version: String             // 世界版本标识（诊断用；互动 UI 请按 mode 决策）
    public let aspectRatio: String?        // 画幅（"9:16" / "16:9"）；仅 acting 有值，其余模式为 nil
}

// 控制接口返回（SDK 出参，非 Codable；status 为对外枚举 OysterTravelStatus）
public struct OysterTravelStateData: Equatable, Sendable { public let encryptedTravelId: String; public let status: OysterTravelStatus }
public struct OysterRewindTravelData: Equatable, Sendable { public let encryptedTravelId: String; public let status: OysterTravelStatus; public let resumedAtSec: TimeInterval }
public struct OysterEndTravelData: Equatable, Sendable { public let encryptedTravelId: String; public let status: OysterTravelStatus; public let endedAt: Date; public let duration: TimeInterval }
public struct OysterSendInstructData: Equatable, Sendable { public let encryptedTravelId: String; public let content: String; public let accepted: Bool }

// 世界探索模式操控指令（强类型枚举；取值与内部 WorldControlParams 对齐）
public struct OysterAdventureCommand: Equatable, Sendable {
    public enum Translation: String { case none, front, back, left, right, frontLeft, frontRight, backLeft, backRight }
    public enum Rotation: String { case none, mouseUp, mouseDown, mouseLeft, mouseRight, mouseUpLeft, mouseUpRight, mouseDownLeft, mouseDownRight }
    public enum Interaction: String { case none, jump, attack, crouch, sprint }
    public let translation: Translation   // 本条指令的移动方向；持续移动时按帧提交，松开后停止提交
    public let rotation: Rotation          // 本条指令的视角方向；持续转动时按帧提交，松开后停止提交
    public let interaction: Interaction    // 本条指令的单次动作；调用一次即可
    public init(translation: Translation = .none, rotation: Rotation = .none, interaction: Interaction = .none)
    public init(_ params: WorldControlParams)   // 由默认控件 WorldControlParams 便捷桥接（rawValue 一致）
}

// 统一错误（见"错误码"章节）
public struct OysterSDKError: Error {
    public let code: Int
    public let raw: Any?                  // 原始信息（内部 OysterError、网关 request_id 等），不承诺结构稳定
    public var kind: OysterErrorKind      // 数字 code 的类型化视图，便于穷尽 switch（计算属性）
    public init(code: Int, raw: Any? = nil)
    // 错误码常量见嵌套的 OysterSDKError.Code（如 .notInitialized = 100001）
}

// 错误码的类型化语义视图：本地码为具名 case，服务端 4xxxxx/5xxxxx 收敛为 .server(code:)
public enum OysterErrorKind: Equatable, Sendable {
    case notInitialized, tokenMissing, tokenInvalid, noActiveTravel, invalidState, sendCommandInDirecting
    case concurrentTravel, realtimeConnectFailed, realtimeJoinTimeout, firstFrameTimeout
    case channelNotReady, callbackTimeout, localNetwork, responseDecodeFailed
    case streamAutoEnd, proxyOrUnrecognized, featureGateDisabled
    case server(code: Int), unknown(code: Int)
}