Stooland Docs

Appearance

Open 服务微服务 API 接口文档 (针对外部调用方) ​

open 模块聚合了包括火山引擎（大模型、视频/图片生成、语音合成）以及阿里云（ICE 媒体处理）等核心 AI 及基建能力。 此文档旨在为**外部服务端（如 hotel-web 等）**提供调用指引。

1. 基础约定 ​

  • 服务前缀: /open/service
  • 接口协议: HTTPS / HTTP
  • 数据格式: 请求与响应均采用 application/json
  • 鉴权方式: 基于 Header 的无状态签名校验 (AppKey + AppSecret)

2. 鉴权机制 (ServiceAuth) ​

为了安全控制流量并识别调用方，所有 /open/service/* 路由均要求提供签名。调用方需向平台申请分配 App-Id 和 App-Secret。

2.1 必须的 HTTP Header ​

在每次发起 HTTP 请求时，必须在 Header 中携带以下字段：

  • X-App-Id: 分配的 AppId (例如：hotel_web)
  • X-Timestamp: 当前时间戳 (Unix Timestamp，精确到秒。注意：服务端会校验时间戳，超过 5 分钟的请求将被拒绝)
  • X-App-Signature: 签名字符串 (小写)

2.2 签名生成算法 ​

签名采用标准的 MD5 算法： Signature = MD5( AppId + AppSecret + Timestamp )

PHP 示例代码:

php
$appId = 'hotel_web';
$appSecret = 'hotel_web_secret_key_2026'; // 请替换为实际分配的 Secret
$timestamp = time();

// 拼接字符串并求 MD5
$signature = md5($appId . $appSecret . $timestamp);

$headers = [
    'X-App-Id: ' . $appId,
    'X-Timestamp: ' . $timestamp,
    'X-App-Signature: ' . $signature,
    'Content-Type: application/json'
];

3. 最佳实践与避坑指南 (前端 SDK 直连推荐) ​

强烈建议：前端或外部系统尽量采用“STS凭证 + 官方SDK直连”的架构模式。

  • 原因：大模型生成的长文本、长视频轮询、媒体文件直传，如果在 open 后端进行代理中转，会极大消耗服务器带宽并引发 cURL timeout（超时）问题。
  • 做法：调用本开放平台的 /sts 或 /token 接口获取具有短期有效性的临时鉴权凭证。前端拿到凭证后，初始化火山/阿里官方提供的 Web SDK 或 Node SDK，由客户端直接与云厂商的边缘节点通信。

4. API 接口列表 ​

4.1 火山引擎大模型能力 (Volcengine) ​

4.1.0 获取火山引擎临时安全凭证 (STS) 🔥推荐 ​

  • 接口路径: GET /open/service/volcengine/sts
  • 说明: 返回前端初始化火山 SDK 所需的临时凭证（包含 AccessKeyId, SecretAccessKey, SessionToken 等）。
  • 主要参数:
    • ttl (int, 选填): 凭证有效期（秒），默认 3600。

4.1.1 获取可用模型列表 ​

  • 接口路径: GET /open/service/volcengine/models
  • 说明: 获取当前系统支持的火山引擎及 DeepSeek 模型列表。

4.1.2 大模型对话生成 (Chat) ​

  • 接口路径: POST /open/service/volcengine/ark
  • 说明: 发送会话消息，获取大模型回复。
  • 主要参数:
    • model (string, 必填): 模型名称，如 doubao-seed-2-0-pro-260215
    • messages (array, 必填): OpenAI 格式的消息数组

4.1.3 大模型纯文本生成 (Text) ​

  • 接口路径: POST /open/service/volcengine/text
  • 说明: 非流式/非会话的直接文本生成，通常用于短文本或指令执行。

4.1.4 提交视觉生成任务 (图片/视频) ​

  • 接口路径: POST /open/service/volcengine/visual/submit
  • 说明: 提交基于 Seedance/Seedream 的视频或图片生成异步任务。
  • 主要参数:
    • req_key (string, 必填): 任务类型标识
    • prompt (string): 提示词
    • image_urls (array): 参考图数组

4.1.5 查询视觉生成结果 ​

  • 接口路径: POST /open/service/volcengine/visual/result
  • 说明: 根据 task_id 轮询查询异步生成任务的结果。
  • 主要参数:
    • req_key (string, 必填): 任务类型标识
    • task_id (string, 必填): 提交时返回的 Task ID

4.1.6 语音合成 TTS (V1) ​

  • 接口路径: POST /open/service/volcengine/tts/synthesize
  • 说明: 基于火山 1.0 的文本转语音。

4.1.7 语音合成 TTS (V3 Seed-TTS) ​

  • 接口路径: POST /open/service/volcengine/tts/v3/synthesize
  • 说明: 基于火山最新 Seed-TTS 模型的拟真语音合成。
  • 主要参数:
    • text (string, 必填): 要合成的文本
    • voice_type (string, 必填): 音色 ID

4.1.8 获取可用音色列表 ​

  • 接口路径: GET /open/service/volcengine/tts/voices
  • 说明: 获取 TTS 服务支持的所有音色列表。

4.2 阿里百炼 / 通义千问能力 (Bailian) ​

目前系统将阿里云的大模型能力统一聚合在了 bailian 路由前缀下，既包含标准的对话/文本能力，也包含了视频分析和选题生成的特色能力。

4.2.0 获取百炼临时直连 Token 🔥推荐 ​

  • 接口路径: GET /open/service/bailian/token
  • 说明: 返回前端直连百炼 WebSocket 或 HTTP 大模型流式输出所需的临时鉴权 Token。
  • 主要参数:
    • ttl (int, 选填): 凭证有效期（秒），默认 3600。

4.2.1 百炼大模型对话 ​

  • 接口路径: POST /open/service/bailian/chat
  • 说明: 标准的 OpenAI 兼容对话接口。
  • 主要参数:
    • model (string): 模型名称，如 qwen-plus、qwen3-max
    • messages (array): 会话消息数组
    • options (array): 采样参数（如 temperature）

4.2.2 百炼文本生成 ​

  • 接口路径: POST /open/service/bailian/text
  • 说明: 纯文本生成，通常用于系统内部的 Prompt 组装任务。

4.2.3 获取百炼可用模型 ​

  • 接口路径: GET /open/service/bailian/models

4.2.4 视频内容分析 ​

  • 接口路径: POST /open/service/bailian/analyze
  • 说明: 基于传入的视频链接，利用多模态大模型分析视频特征与受众。
  • 主要参数: videoLinks (array)

4.2.5 选题生成 ​

  • 接口路径: POST /open/service/bailian/topics
  • 说明: 基于上一步的视频分析结果，生成相关短视频选题。

4.3 阿里云媒体服务 (Aliyun ICE) ​

4.2.1 URL 上传媒体文件 ​

  • 接口路径: POST /open/service/ali/ice/uploadMediaByUrl
  • 说明: 将公网可访问的音视频 URL 异步拉取并注册到 ICE 媒体库中。

4.2.2 查询 URL 上传进度 ​

  • 接口路径: POST /open/service/ali/ice/getUrlUploadInfos
  • 说明: 查询上一步异步拉取的进度及生成的 MediaId。

4.2.3 提交智能媒体合成任务 ​

  • 接口路径: POST /open/service/ali/ice/submitMediaProducing
  • 说明: 根据指定的 Timeline (时间线) 结构，向云端提交视频剪辑与合成任务。

4.2.4 查询合成任务状态 ​

  • 接口路径: POST /open/service/ali/ice/getMediaProducingJob
  • 说明: 轮询查询视频剪辑任务的完成状态及最终成片地址。

4.3.5 获取阿里云临时安全凭证 (STS) 🔥推荐 ​

  • 接口路径: GET /open/service/ali/sts
  • 说明: 获取直传阿里云 OSS 或调用前端 SDK 所需的临时 Token 凭证（包含 AccessKeyId, AccessKeySecret, SecurityToken 等）。这是前端直连阿里云的最佳实践。

4.3.6 获取预签名 URL (PresignUrl) ​

  • 接口路径: POST /open/service/ali/ice/getPresignUrl
  • 说明: 获取 OSS 文件的带签名访问链接，常用于私有 Bucket 文件的临时预览。
  • 主要参数:
    • bucket (string, 必填): 存储空间名称
    • key (string, 必填): 文件路径/对象键
    • region (string, 选填): 区域，默认为 cn-shenzhen

4.3.7 获取直传临时 URL (DirectUploadUrl) ​

  • 接口路径: POST /open/service/ali/ice/getDirectUploadUrl
  • 说明: 获取一个可以直接用于 PUT 上传文件的预签名 URL。
  • 主要参数:
    • bucket (string, 必填): 存储空间名称
    • key (string, 必填): 上传目标路径
    • expires (int, 选填): 有效期秒数，默认 3600
    • region (string, 选填): 区域，默认为 cn-shenzhen

4.3.8 注册媒体素材信息 ​

  • 接口路径: POST /open/service/ali/ice/registerMediaInfo
  • 说明: 注册 OSS 或 URL 素材为 ICE 媒体，返回该素材在媒资库中的 MediaId。
  • 主要参数:
    • 参照阿里云 ICE API 官方的 RegisterMediaInfo 参数结构。