↓
Rivya AI 文档

Rivya TypeScript SDK

使用测试版 Rivya TypeScript SDK 调用 Public API v1,覆盖模型、生成、文件、积分、Webhook,以及支持 SSE 流式响应的 Chat。

最近审阅于 2026年11月11日

Rivya 提供 TypeScript SDK beta,用于服务端 Public API 集成。

SDK 是 Rivya Public API v1 的薄客户端。底层合同仍以 OpenAPI 与 Schema 合同 为准,SDK 方法必须和 schema 保持一致。

本文介绍的是已经实现的 Public API v1 合同。实际运行仍取决于部署是否启用 Public API、账号是否有有效 API key,以及所选模型是否在实时模型列表中显示为 API 可用;文档存在不代表所有环境都能调用。

提示词单位与完整图层结果

读取 GET /api/v1/models 时,请将 prompt_length_unit 与 max_prompt_length 一起使用。utf8_bytes 计算原文的 UTF-8 字节,包含空格和换行;utf16_code_units 计算 JavaScript 的 UTF-16 代码单元。上限为 null 不代表文字不限长或可以不填。Gemini TTS 使用字节单位。

已完成的图层拆分结果可在完整的 result.urls 之外提供 result.layers。请保留每层返回的 z_index、URL、尺寸、名称、说明和边界框,索引零是底图。TypeScript SDK 已提供这些字段。参考文件必须按所选模型上传,并传回原始签名元数据;单独声明尺寸或时长不能代替核验。

状态

@rivya/sdk 是尚未发布到 npm 的私有测试版。运行示例前,需要取得 Rivya 私有 SDK 源码,并构建能解析 @rivya/sdk 的环境。

客户端提供模型查询、异步生成任务创建与查询、Files API 上传与查询、积分余额查询、Webhook 端点管理与测试投递、事件与投递记录查询、密钥轮换、签名校验,以及非流式和流式 Chat 与 API 会话方法。流式 Chat 使用服务端 SSE 解析;秘密 API 密钥应留在服务端。

在当前仓库中使用

以下命令适用于已安装依赖的 Rivya 源码检出目录,只检查 SDK 源码,不从 npm 下载私有测试版,也不构建导出的包:

pnpm --dir packages/rivya-sdk typecheck

服务端运行环境需要 fetch、Headers、FormData、Blob 和 AbortController;Webhook 验证还需要 globalThis.crypto.subtle。包导入和秘密密钥都应放在服务端:

import { RivyaClient } from "@rivya/sdk";

const rivya = new RivyaClient({
  apiKey: process.env.RIVYA_API_KEY
});

不要把秘密 API 密钥放进浏览器包、localStorage、分析事件、截图或共享工单。

除 apiKey 外,RivyaClient 接受 baseURL、timeoutMs、fetch 和 defaultHeaders,默认基础地址为 https://rivya.ai,超时为 60,000 毫秒。请求选项支持 idempotencyKey、headers 和 signal;SDK 不自动重试或轮询。

查询模型

models.list 是公开接口,不需要 API 密钥:

const models = await rivya.models.list();

for (const model of models.data) {
  console.log(model.id, model.api_status, model.supported_api_inputs);
}

列表也包含当前不能调用的发现记录。展示模型或控制项前,检查 api_status、supported_api_inputs、file_kinds 和 chat_capabilities。coming_soon、temporarily_unavailable 和 studio_only 模型不能通过 Public API 调用;SDK 不会额外开放提供商专有功能。

创建生成任务

对可用的异步图片、视频或音频模型使用 generations.create;聊天模型使用独立的 Chat 方法:

const generation = await rivya.generations.create(
  {
    model: "z-image",
    prompt: "A clean editorial product image on a soft studio background",
    client_request_id: "order-123-preview"
  },
  {
    idempotencyKey: "order-123-preview"
  }
);

console.log(generation.id, generation.status);

generations.retrieve 读取当前 API 密钥所属账号的任务,并可能刷新状态,需要 generations:read。SDK 不自动轮询;状态为 queued 或 processing 时需再次查询:

const current = await rivya.generations.retrieve(generation.id);
console.log(current.status, current.result?.primary_url);

succeeded 和 failed 是任务终态,不能证明积分已结算。成功结果的 primary_url 仍可能为 null;检查 result.urls 和 settlement_status。HTTP 请求失败也不代表生成任务失败。参阅生成状态与API 积分。

idempotencyKey 设置 Idempotency-Key 请求头。生成和 Chat POST 的每个新任务或新轮次使用新键;核查结果不明的请求时,保持原 API 密钥、幂等键和正文不变。已存响应可以重放;处理中记录或不同正文可返回 idempotency_conflict。client_request_id 只是跟踪标签,不能防止重复请求。

上传文件

使用具有 files:create 权限的密钥调用 files.upload,上传模型接受的参考素材类型。需要签名元数据的模型须绑定该生成模型 ID:

import { readFile } from "node:fs/promises";

const file = new Blob([await readFile("./reference.png")], {
  type: "image/png"
});

const uploaded = await rivya.files.upload({
  file,
  filename: "reference.png",
  kind: "image",
  model: "nano-banana-2-lite",
  client_request_id: "asset-123"
});

console.log(uploaded.id, uploaded.url);

files.retrieve 需要 files:read,读取账号拥有的可用文件,可能重新签发时长 token,但不会重复上传响应的全部元数据:

const sameFile = await rivya.files.retrieve(uploaded.id);
console.log(sameFile.mime_type, sameFile.duration_token);

保留原始上传响应。当前 GET 中 width、height、image_dimensions_token、video_width、video_height、frames_per_second、video_bitrate_mbps、video_file_size_bytes 和 video_metadata_token 始终为 null。GET 签发的音频时长 token 不绑定 MIME 或字节数,不能替代要求这些字段的原始上传 token。

接受 referenceMediaItems 的生成请求须把原始响应映射到 params.referenceMediaItems。下例沿用同一次 nano-banana-2-lite 上传,不能更改签名字段对应的 URL、模型、MIME、尺寸或大小:

await rivya.generations.create({
  model: "nano-banana-2-lite",
  prompt: "Restyle this product photo for a clean editorial catalog page",
  params: {
    referenceMediaItems: [
      {
        url: uploaded.url,
        kind: uploaded.kind,
        name: uploaded.file_name,
        mimeType: uploaded.mime_type,
        durationSeconds: uploaded.duration_seconds ?? undefined,
        durationToken: uploaded.duration_token ?? undefined,
        width: uploaded.video_width ?? uploaded.width ?? undefined,
        height: uploaded.video_height ?? uploaded.height ?? undefined,
        sizeBytes: uploaded.video_file_size_bytes ?? uploaded.size_bytes,
        imageDimensionsToken: uploaded.image_dimensions_token ?? undefined,
        framesPerSecond: uploaded.frames_per_second ?? undefined,
        videoBitrateMbps: uploaded.video_bitrate_mbps ?? undefined,
        videoMetadataToken: uploaded.video_metadata_token ?? undefined
      }
    ]
  }
});

seedream-5-pro、seedream-5-pro-layer-decomposition、nano-banana-2-lite、qwen-image-3、qwen-image-3-pro 和 grok-imagine-image-2-0 的参考图需要原始模型绑定上传的 mime_type、width、height、size_bytes、image_dimensions_token,依次映射为 mimeType、width、height、sizeBytes、imageDimensionsToken。token 过期或原响应丢失时,用同一模型 ID 重新上传,不猜测元数据。

图层拆分只接受一张图片并校验几何边界;Grok Imagine Image 2.0 编辑接受 1–5 张签名 JPEG、PNG 或 WebP 参考图。查看模型参考了解当前模式和限制。

seedance-2-mini、seedance-2-5、minimax-h3、gemini-omni-video、gemini-omni-flash-1-1 和 volcengine-video-lip-sync 的参考视频需要原上传的 video_width、video_height、frames_per_second、video_bitrate_mbps、video_file_size_bytes、video_metadata_token,依次传为 width、height、framesPerSecond、videoBitrateMbps、sizeBytes、videoMetadataToken。另保留 durationSeconds 和 durationToken 时长证明。证明缺失或过期须重新上传;GET 不能恢复 video_metadata_token。选择视频输入前查看API 模型。

Wan 3.0 每份参考素材均须以 model: "wan-3-0-video" 上传。text、frames、reference 三个场景互斥;图片需要上述签名图片字段,视频同时需要时长和视频元数据证明,音频需要原始 POST 响应的 mimeType、sizeBytes、durationSeconds、durationToken 对应值。音频 token 必须绑定 MIME 和大小,GET 重签 token 不能替代。

在 params 设置 seedance_scene、variant、resolution、aspect_ratio、duration、audio 及可选 seed。duration: -1 为智能时长,按 30 秒输出预留积分,不能结合参考视频;有参考视频时,计费时长包括输出与已验证的输入视频秒数。不提供文件转视频或链接转视频快捷入口。

上传 URL 有时效性。保留源文件,URL 或必需 token 不可用时重新上传;Files 记录不保证永久保存媒体。

查询积分

credits.retrieve 需要 credits:read,返回与 Studio 共用的钱包余额,不提供请求报价,也不能确认某笔退款:

const credits = await rivya.credits.retrieve();
console.log(credits.current_credits);

管理 Webhooks

部署启用 Webhook 且账号密钥具有 webhooks:manage 时,可使用符合规则的公开 URL 创建端点:

const endpoint = await rivya.webhooks.create({
  name: "Production webhook",
  url: "https://example.com/rivya/webhook",
  event_types: ["generation.succeeded", "generation.failed"]
});

const signingSecret = endpoint.signing_secret;
console.log(endpoint.id);

创建或轮换时把 signing_secret 安全保存在服务端;普通列表和查询响应不包含它。

仅对启用中的端点使用 webhooks.test,它会向注册 URL 尝试真实投递。保存 webhooks.rotateSecret 返回的新密钥;轮换不为旧密钥提供宽限期:

await rivya.webhooks.list();
await rivya.webhooks.retrieve(endpoint.id);
await rivya.webhooks.test(endpoint.id);
await rivya.webhooks.update(endpoint.id, { status: "disabled" });
const rotatedEndpoint = await rivya.webhooks.rotateSecret(endpoint.id);
const rotatedSigningSecret = rotatedEndpoint.signing_secret;
await rivya.webhooks.deliveries.list(endpoint.id, { limit: 20 });
await rivya.webhookEvents.list({ limit: 20 });

信任 Webhook 正文前先验证签名。下例 rawBody 是未修改的请求正文字符串,request 是收到的请求,验证后再解析:

import { verifyRivyaWebhookSignature } from "@rivya/sdk";

const ok = await verifyRivyaWebhookSignature({
  rawBody,
  timestamp: request.headers.get("rivya-webhook-timestamp") || "",
  signatureHeader: request.headers.get("rivya-webhook-signature") || "",
  signingSecret: process.env.RIVYA_WEBHOOK_SIGNING_SECRET || ""
});

if (!ok) {
  throw new Error("Invalid Rivya webhook signature");
}

辅助方法校验时间戳和原始正文的 HMAC-SHA256,默认拒绝与本地时钟相差超过 300 秒的时间戳。需要 Web Crypto,缺少该 API 时可能抛错。签名格式见 API Webhooks。

Chat

使用 chat:create 和可用聊天模型,通过 chat.completions.create 发送一轮非流式请求。当前可调用的 Claude 模型支持文本和思考模式,不支持图片附件、网络搜索或可选推理强度;以 chat_capabilities 为准:

const completion = await rivya.chat.completions.create(
  {
    model: "claude-sonnet-5-chat",
    message: "Write a concise launch plan for a new product image campaign",
    client_request_id: "chat-001"
  },
  {
    idempotencyKey: "chat-001"
  }
);

console.log(completion.session_id, completion.message.content);

用返回的 session_id、同一模型和下一轮的新幂等键继续:

await rivya.chat.completions.create(
  {
    model: "claude-sonnet-5-chat",
    session_id: completion.session_id,
    message: "Now turn that into a 5-step execution checklist."
  },
  {
    idempotencyKey: "chat-002"
  }
);

读取会话需要 chat:read。仅返回账号的 API 会话,不能读取仅在 Studio 创建的会话;同账号的浏览器聊天历史也可能包含 API 会话:

await rivya.chat.sessions.list({ limit: 20 });
await rivya.chat.sessions.retrieve(completion.session_id);

用 chat.completions.stream 的异步迭代器读取 SSE,同时处理初始调用和后续迭代的错误:

const stream = await rivya.chat.completions.stream(
  {
    model: "claude-sonnet-5-chat",
    message: "Write a concise launch plan for a new product image campaign",
    client_request_id: "chat-stream-001"
  },
  {
    idempotencyKey: "chat-stream-001"
  }
);

for await (const event of stream) {
  if (event.event === "message.delta") {
    process.stdout.write(event.data.delta);
  }

  if (event.event === "message.completed") {
    console.log(event.data.message.id);
  }
}

message.delta 用于展示,不能证明回复已保存;message.completed 确认助手消息已提交。断线或错误后用会话 ID 调用 chat.sessions.retrieve 核查。断线或迭代器直接到达 EOF 都不能证明未保存。

usage.completed 包含 credits.settlement_status。done 代表流成功结束,不保证积分已结算。测试版迭代器不强制要求 done,并静默跳过无法解析的 SSE 帧;需显式核查消息与结算,部分响应或中断不保证退款。参阅 Chat API。

错误处理

SDK 对能读取的非 2xx HTTP 响应抛出 RivyaAPIError;缺少本地 API 密钥、解析到 Chat 错误事件及部分流检查也使用该类型:

import { RivyaAPIError } from "@rivya/sdk";

try {
  await rivya.generations.retrieve("task_missing");
} catch (error) {
  if (error instanceof RivyaAPIError) {
    console.log(error.status, error.code, error.requestId);
  } else {
    throw error;
  }
}

它包含消息、状态、可选错误码和请求 ID,以及允许公开的响应头子集。非 2xx 时 status 为 HTTP 状态;Chat 流错误事件使用 SDK 状态 500,即使流以 HTTP 200 开始。缺少响应流正文或出现意外事件名也可能产生 SDK 错误。

网络、中止和正文读取错误可能以其他错误类型传播。成功 HTTP 响应尽可能按 JSON 解析,失败则返回文本,不按 TypeScript 类型验证;识别到的 SSE 帧也不做 schema 校验。错误类型不能证明写入是否生效,重试前核查原任务或会话。

验证

维护者在 Rivya 源码目录修改客户端后运行:

pnpm sdk:check
pnpm --dir packages/rivya-sdk typecheck
pnpm content:api-docs

pnpm sdk:check 结合 SDK/OpenAPI/文档静态比对与无网络模拟运行检查,覆盖错误解析、安全错误头、幂等头、Bearer 鉴权、公开模型列表、Chat SSE 解析与错误事件、Webhook 签名。它不调用提供商,也不证明模型可用、退款结算或 SSE 完整送达。

相关页面