Skip to main content

HappyOyster-Directing-客户端进入房间 API参考

客户端使用 ticket 创建实际 Travel,并获取 RTC 入会配置和 Directing 能力版本。creationModel 决定 Travel 可调用的控制接口。

适用范围

客户端使用 ticket 创建实际 Travel,并获取 RTC 入会配置。调用前请确认以下事项:
  • 鉴权要求:不强制主 API Key,使用 ticket 完成进房校验。获取方式请参见获取鉴权凭证。
  • 前置条件:ticket 由获取体验凭证接口换取,未过期且未使用,对应 World 状态为 ready。
  • 调用方:您的客户端调用。

HTTP调用

  • 新加坡
  • 美国(弗吉尼亚)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/enter-travel调用时请将{WorkspaceId}替换为真实的Workspace ID。

请求参数

  • 客户端进入房间
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/enter-travel' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "ticket": "{ticket}"
}'
Content-Typestring(必选)请求内容类型。此参数必须设置为application/json。
Authorization string (必选)API Key 鉴权。不强制主 API Key,主 API Key 或临时 API Key 均可调用。
  • 主 API Key:以 sk- 开头,如 sk-xxx。
  • 临时 API Key:以 st- 开头,如 st-xxx。
请求体(Request Body)
ticket string (必选)未过期且未使用的一次性凭证。由获取体验凭证接口换取。同一 ticket 再次使用返回 401011。
Directing 进房不消费 maxExperienceTimeSec,请勿传入。该字段仅 Adventure 生效;若仍传入非法档位,会在模型分流前返回 400000。成功响应仍为 null。

响应参数

进房成功
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "encryptedWorldId": "enc_a1b2****",
        "mode": 2,
        "creationModel": "simple",
        "playUrl": null,
        "firstFrame": "https://cdn.happyoyster.com/frames/world_xyz789.jpg",
        "rtcConfig": {
            "channelId": "stream_abc123",
            "appId": "18bca2e3218c46aebf8ff3a32fb12311",
            "token": "007eJxTYOh...",
            "userId": "user_1"
        },
        "version": "storyV2",
        "aspectRatio": null,
        "noStreamAutoEndTimeoutSec": 30,
        "maxExperienceTimeSec": null
    }
}
code integer返回码。0 表示成功,非 0 为错误码。
message string错误信息。成功时为 null。
data object响应数据。失败时为 null。

属性

encryptedTravelId string新创建的加密 Travel ID。后续查询Travel状态、回溯、暂停、恢复、结束、产物查询均使用此值。encryptedWorldId string当前 Travel 对应的加密 World ID。mode integerDirecting 恒为 2。creationModel stringsimple 或 scriptlist;决定 Travel 可调用的控制接口:
  • simple:instruct、pause、resume、rewind、end
  • scriptlist:update-script、pause、resume、rewind、end(不支持 instruct)
playUrl null暂不可用,固定为 null。firstFrame stringWorld 首帧 URL。rtcConfig objectRTC 入会配置;没有可用推流频道时为 null,客户端不能据此开始播放。
  • channelId:RTC 频道 ID
  • appId:平台分配的 RTC 应用 ID
  • token:RTC 入会 Token
  • userId:RTC 入会用户 ID,固定为 user_1
version stringDirecting 进房版本,固定为 storyV2。aspectRatio nullDirecting 模型固定为 null。noStreamAutoEndTimeoutSec integer无推流自动结束超时秒数,默认 30,以实际响应为准。进房后若在此时间内 rtcStatus 未进入推流态,应调用结束Travel并传入 failCode=TRAVEL_NO_STREAM_AUTO_END。maxExperienceTimeSec nullDirecting 模型固定为 null。

前置状态与调用注意事项

  • ticket 对应的 World 必须为 ready,且 ticket 未过期、未使用。
  • 不要传 maxExperienceTimeSec。Directing 不按该字段限制体验时长。
  • 调用成功即创建 Travel;同一 ticket 再次使用返回 401011。
  • creationModel=scriptlist 时不要调用 instruct,应使用剧本全量更新。
  • rtcConfig=null 表示当前没有可用推流频道,客户端不能据此开始播放。

错误码

如果模型调用失败并返回报错信息,请参见HappyOyster 错误码进行解决。

下一步

进房成功后:
文本生成
图像生成
视频生成
3D模型生成
音频
  • 音频生成
Realtime API
  • 概述
向量与排序
决策模型
TokenPlan
模型生产