消费 SDK 与接入指南

From the smallest request to error handling, streaming settlement, and Trace drill-down.

统一消费接入

Verify the current user's purchased rights on the server, resolve customer/product ownership, then reserve, execute, settle or release under one business key.

四语言完整文档

Unified consumption SDK

Language

Signed-in user → verify personal/team/seat rights → access or reserve → execute and settle; stop on denial.

Personal, shared, seat and revocation rules

Personal access binds the purchaser; team access requires active account membership; seat access requires the user's effective assignment.
Recheck after expiry, benefit-reversing refunds and member removal. Network failures must not allow access.
Pass the user JWT only in a request-scoped client or Go context. Keep it out of journals, and service keys out of browsers.
Admission checks protect new work; settle or release executed work through the original journal without rerunning business callbacks.

capabilityId + bundleProductId; reserve an estimate and settle trusted final usage.

Complete QUOTA workflow example

import { NexusClient, PostgresConsumptionJournal } from '@rainlib/nexus-sdk';

// dbPool 是应用已有的 PostgreSQL Pool；凭证从应用现有配置注入。
const nexus = new NexusClient({
  baseUrl: config.nexusUrl, apiKey: config.nexusKey,
  tenantId: team.nexusTenantId, environmentId: team.nexusEnvironmentId,
  subjectToken: session.nexusAccessToken,
});
const consume = nexus.consumption({
  applicationId: 'my-service', journal: new PostgresConsumptionJournal(dbPool),
});
const request = {
  businessId: job.id, customerAccountId: job.customerId,
  kind: 'QUOTA' as const, capabilityId: job.capabilityId,
  bundleProductId: job.purchasedProductId, estimatedQuantity: '100',
};
await nexus.deliveries.requireUserAccess({
  customerAccountId: job.customerId, capabilityId: job.capabilityId,
  productId: job.purchasedProductId, action: 'consume', businessId: job.id,
});
const result = await consume.run(request, async receipt => {
  // 先保存供应商请求标识，供超时或重启后查询；不在这里另调一次 Nexus Gateway。
  const output = await provider.execute(job, { idempotencyKey: receipt.journalKey });
  await saveBusinessResult(job.id, output);
  return { value: output, actualQuantity: output.authoritativeUsage };
});
// replayed=true 时不会重跑 callback；从业务数据库读取之前保存的结果。
const output = result.replayed ? await loadBusinessResult(job.id) : result.value;

The code demonstrates a usage pack. Other types use their resource identifiers, quantities and facts; consult the matching SDK version.

Open complete SDK documentation →

归属、预扣与四类交付说明

01 · 确认归属组织、环境、客户、能力与购买商品均来自可信服务端。
02 · 预扣并执行稳定业务 ID + 持久 Journal；外部调用使用原幂等键。
03 · 真实量结算结算 80、释放 20；未知结果保留预扣并进入待确认。

ACCESS · Content and feature accessresourceId · 数量固定为 1，派发前检查资格，不创建钱包扣款。
QUOTA · API/AI usage packcapabilityId + bundleProductId · 传递已购商品，预计量预扣，最终可信用量结算。
CAPACITY · Storage capacityresourceId · 按字节预留与确认占用；实际为 0 时释放。
SEAT · Member seatsresourceId + memberId · Use an active account member's internal user ID, quantity 1; confirm the seat and release only when intentionally revoked.

TypeScript、Python、Go、Java 的方法及依赖以完整文档和对应版本源码为准。持久 Journal 使用业务数据库；源码合并与软件包发布分别验证。

模型网关已管理预扣与结算；直接调用网关时，按网关文档接入。业务结果未知时进入 CONSUMPTION_PENDING，沿原记录恢复，保留原幂等键和冻结额度。

查看待结算查看待确认与复核

Turn an invocation into a recoverable, settlement-ready business outcome.

A business record establishes the idempotency boundary; the gateway handles reservation, model routing, and usage reporting. Applications decide only by stable code 和 retryable signals.

REST address: https://pay.bytecome.com
Authentication: Bearer API Key
Idempotency: X-Nexus-Operation-Key
Tracing: W3C traceparent

01 / Smallest runnable call

Use a published capability route first, then fix the business transaction.

Do not send an upstream provider key; Nexus resolves the model alias, offer, token cap, and pricing snapshot.

1AuthenticateThe API key determines the customer and scope.

2ReserveReserve the maximum risk amount.

3ExecuteRoute to a published provider.

4SettleSubmit usage and refund the difference.

Current public REST endpointhttps://pay.bytecome.com

OpenAI-compatible requestcURL

export NEXUS_API_URL="https://pay.bytecome.com"

curl "$NEXUS_API_URL/v1/openai/chat/completions" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "X-Nexus-Operation-Key: order-2026-00042" \
  -H "traceparent: 00-<trace-id>-<span-id>-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"support-chat","messages":[{"role":"user","content":"..."}]}'

modelEnter only the route alias published by the capability, for example support-chat。

operation keyKeep it unchanged across retries of the same business transaction to avoid duplicate reservations.

traceparentOptional. After forwarding it, inspect model, tool, and billing stages from Trace.

正在加载页面内容。

import { NexusClient, PostgresConsumptionJournal } from '@rainlib/nexus-sdk'; // dbPool 是应用已有的 PostgreSQL Pool；凭证从应用现有配置注入。 const nexus = new NexusClient({ baseUrl: config.nexusUrl, apiKey: config.nexusKey, tenantId: team.nexusTenantId, environmentId: team.nexusEnvironmentId, subjectToken: session.nexusAccessToken, }); const consume = nexus.consumption({ applicationId: 'my-service', journal: new PostgresConsumptionJournal(dbPool), }); const request = { businessId: job.id, customerAccountId: job.customerId, kind: 'QUOTA' as const, capabilityId: job.capabilityId, bundleProductId: job.purchasedProductId, estimatedQuantity: '100', }; await nexus.deliveries.requireUserAccess({ customerAccountId: job.customerId, capabilityId: job.capabilityId, productId: job.purchasedProductId, action: 'consume', businessId: job.id, }); const result = await consume.run(request, async receipt => { // 先保存供应商请求标识，供超时或重启后查询；不在这里另调一次 Nexus Gateway。 const output = await provider.execute(job, { idempotencyKey: receipt.journalKey }); await saveBusinessResult(job.id, output); return { value: output, actualQuantity: output.authoritativeUsage }; }); // replayed=true 时不会重跑 callback；从业务数据库读取之前保存的结果。 const output = result.replayed ? await loadBusinessResult(job.id) : result.value;

export NEXUS_API_URL="https://pay.bytecome.com" curl "$NEXUS_API_URL/v1/openai/chat/completions" \ -H "Authorization: Bearer $NEXUS_API_KEY" \ -H "X-Nexus-Operation-Key: order-2026-00042" \ -H "traceparent: 00-<trace-id>-<span-id>-01" \ -H "Content-Type: application/json" \ -d '{"model":"support-chat","messages":[{"role":"user","content":"..."}]}'