opg
0 中 EN 开始使用

Guides

把一个 AI 应用接入 OPG

从环境准备、平台授权、App Developer Grant、SDK 客户端、AI 调用到视频任务，按顺序完成一次可上线的接入。

约 30 分钟 面向独立开发者和小团队

开始前准备

  • Node.js 22 或更高版本。
  • 一个可访问的 OPG API 地址，例如 https://your-opg.example.com。
  • 平台管理员账号，用于创建 app 和管理运行时配置。
  • 数据库、对象存储、队列、域名；邮件或短信服务按业务需要配置。
  • 一个要接入 OPG 的 Node.js / TypeScript 应用。
01

初始化本机环境

先让 CLI 知道 OPG 网关地址，并完成平台级登录。平台 token 只用于创建 app、读运营数据和控制面操作，不要放进前端。

  1. 确认本机 Node 版本满足要求。
  2. 用 OPG API 地址初始化本机配置。
  3. 完成平台级浏览器登录。
  4. 确认 .opg/opg.config.json 已写入 base URL 和 profile。
CLI
node --version
opg init --base-url https://your-opg.example.com
opg login

不要提交 .opg/credentials.json，也不要把 OPG_PLATFORM_TOKEN 写进浏览器端代码。

02

创建 App 并授权 Developer Grant

每个业务应用都应该有独立 app slug。Developer Grant 只授权这个 app 的 SDK、数据库、AI、上传、视频和 MCP 能力。

  1. 创建或选择当前 app。
  2. 执行 app 级登录，拿到 Developer Grant。
  3. 拉取 manifest，确认当前 app 暴露了需要的能力。
  4. 运行 smoke check，尽早发现权限或配置缺口。
CLI
opg app create demo --name "Demo App"
opg app use demo
opg login --app demo
opg manifest pull
opg smoke --app demo

Developer Grant 明文只应在创建或登录时出现一次，CI 场景可以通过 OPG_API_KEY 注入。

03

在应用运行时接入 SDK

应用后端从本地配置或环境变量读取 OPG 连接信息。provider key、数据库连接串和平台 token 都不应该进入前端。

  1. 安装 SDK。
  2. 在服务端创建 OPG client。
  3. 启动时读取 manifest，按能力决定页面和接口是否开放。
  4. 把 OPG 调用封装在应用后端 API 内，不让浏览器直接拿敏感凭证。
TypeScript
npm install @jamba/opg-sdk

import {
  createOpgClientFromLocalConfig,
  createOpgPlatformClient,
} from "@jamba/opg-sdk";

const opg = await createOpgClientFromLocalConfig();
const manifest = await opg.sdk.manifest();

const platform = createOpgPlatformClient({
  baseUrl: process.env.OPG_BASE_URL!,
  platformToken: process.env.OPG_PLATFORM_TOKEN!,
});

本地开发优先用 createOpgClientFromLocalConfig()；CI 或部署环境用 OPG_BASE_URL、OPG_APP_SLUG、OPG_API_KEY。

04

通过 AI Gateway 调用模型

文本、图像、语音、embedding 和 agent 都应该走 OPG gateway。应用只提交业务请求，provider、model、额度、usage logs 和失败原因由后端记录。

  1. 在平台控制面配置 provider 和 model。
  2. 应用后端调用 opg.ai.models() 确认可用模型。
  3. 通过 opg.ai.chat() 或 opg.ai.responses() 发起请求。
  4. 把 usage id、成本、失败原因写入业务日志，方便排障和限额。
TypeScript
const models = await opg.ai.models();

const answer = await opg.ai.chat({
  model: "gpt-4.1-mini",
  messages: [
    { role: "system", content: "You are the assistant for this app." },
    { role: "user", content: "Summarize this customer request." },
  ],
});

console.log(answer.output_text ?? answer.text);

不要在应用前端保存 provider key。需要让用户触发 AI 时，前端只调用你的业务 API。

05

把视频生成做成异步任务

视频生成是长耗时、可失败、会消耗额度的任务。HTTP 请求只负责创建任务并返回 task id，UI 根据状态轮询或订阅结果。

  1. 提交任务后立即返回 task_id。
  2. 后端轮询或由 worker 消费队列。
  3. 把成功结果写入对象存储，把失败原因写入任务记录。
  4. UI 只展示 pending、running、succeeded、failed 等状态，不阻塞请求。
TypeScript
const task = await opg.video.generateAsync({
  model: "runninghub-video",
  prompt: "A clean product intro video for OPG",
});

const result = await opg.video.wait(String(task.task_id || task.id));
console.log(result.status, result.output_url);

大文件上传使用 opg.upload.presignedUrl()，不要把视频或大 base64 放进 JSON 请求。

06

上线前检查

上线前重点检查权限边界、长任务、缓存和成本记录。OPG 的目标是让多个 app 可治理，而不是只让第一个 demo 跑起来。

  1. 运行 opg smoke --app demo，确认 manifest、授权、AI、上传和视频能力可用。
  2. 确认前端代码里没有 provider key、Developer Grant、平台 token 或数据库连接串。
  3. 列表接口分页；manifest 短缓存；静态资源长期缓存；用户态数据不公开缓存。
  4. AI、视频、消息、webhook 和批处理进入队列。
  5. 记录 usage、cost、task status、audit event 和失败原因。
Checklist
opg smoke --app demo
opg manifest pull
opg usage inspect --app demo
opg task list --app demo --status failed

如果这一步失败，不要先补 UI 文案，先修权限、provider、队列、对象存储和回调配置。