官方 SDK 与 Embedded 集成

SDK 源码版本为 0.3.0，位于仓库 sdk/typescript、sdk/swift、sdk/kotlin。当前按源码集成，TypeScript 包仍为 private；不能假定已经发布到 npm、Maven 或 Swift 版本标签。官方 SDK 将服务端凭据与终端访问明确分开。

平台	App 后端	终端自助服务	数据 API	令牌接口
TypeScript	`ServerClient`	`EmbeddedClient`	`GatewayClient`	`TokenProvider`
Swift	`CreditPlatformServerClient`	`CreditPlatformEmbeddedClient`	`CreditPlatformGatewayClient`	`CreditPlatformTokenStore`
Kotlin	`CreditPlatformServerClient`	`CreditPlatformEmbeddedClient`	`CreditPlatformGatewayClient`	`TokenStore`

TypeScript

const embedded = new EmbeddedClient({
  baseUrl,
  applicationCode: 'my_app',
  tokenProvider,
})
const wallet = await embedded.getWallet()

ServerClient 只能打包到可信 App 后端。浏览器或共享前端包只使用调用方提供的 TokenProvider。

Swift

swift

let client = try CreditPlatformEmbeddedClient(
    baseURL: baseURL,
    applicationCode: "my_app",
    tokenStore: keychainTokenStore
)
let wallet = try await client.getWallet()

在 iOS 中用 Keychain 支撑 CreditPlatformTokenStore，不要把 AppClient secret 放进 App 包。

Kotlin

kotlin

val client = CreditPlatformEmbeddedClient(
    baseUrl,
    "my_app",
    keystoreBackedTokenStore
)
val wallet = client.getWallet()

Kotlin 包使用 Java 17 java.net.http，目标为 JVM；不能直接当作 Android 原生网络库。所有平台都应把 Application code 固定在客户端构造参数中，不允许业务调用方临时传入其他应用或用户 ID。

SDK 抛出的错误只应包含 HTTP 状态与安全错误码。不要在二次封装时附加完整响应、请求正文或凭据。

网关 SDK 0.3.0

三个平台使用相同的方法命名，覆盖以下非流式接口。baseUrl / baseURL 必须是数据 API 根地址，不带 /v1 或 /v1beta 后缀；SDK 自动添加完整路径。与 OpenAI SDK 的 Base URL 配置不同。

Method	Endpoint
`listPublicModels`	`GET /api/v1/public/models`（无需鉴权）
`listModels`	`GET /v1/models`
`createChatCompletion`	`POST /v1/chat/completions`
`createResponse`	`POST /v1/responses`
`createMessage`	`POST /v1/messages`
`countMessageTokens`	`POST /v1/messages/count_tokens`
`createEmbedding`	`POST /v1/embeddings`
`createImageGeneration`	`POST /v1/images/generations`
`createVideoGeneration`	`POST /v1/videos/generations`
`listGeminiModels` / `getGeminiModel`	`GET /v1beta/models` / `GET /v1beta/models/{model}`
`generateGeminiContent` / `countGeminiTokens`	`POST /v1beta/models/{model}:generateContent` / `:countTokens`
`getBalance` / `getUsage`	`GET /v1/balance` / `GET /v1/usage`

GatewayClient 可通过令牌接口接收平台直连 API Key（sk-）或 Embedded 令牌（axt_）。直连 Key 只放在可信后端；浏览器和终端使用由应用后端换取的短期令牌。EmbeddedClient 仍只接受 axt_，不能用直连 Key 访问用户自助服务。

import { GatewayClient } from '@ai-credits/platform-sdk'

// 可信 Node.js 后端；终端应用改用自己的短期令牌 TokenProvider。
const gateway = new GatewayClient({
  baseUrl: process.env.API_BASE_URL!,
  tokenProvider: { getToken: () => process.env.AICREDITS_API_KEY! },
})
const models = await gateway.listModels()
const result = await gateway.createResponse(
  { model: process.env.MODEL!, input: '<YOUR_PROMPT>' },
  { requestId: crypto.randomUUID(), signal: AbortSignal.timeout(60_000) },
)

swift

let gateway = CreditPlatformGatewayClient(baseURL: baseURL, tokenStore: keychainTokenStore)
let result = try await gateway.createResponse(request: requestJSON,
    options: GatewayRequestOptions(timeout: 60)) // requestJSON 为 UTF-8 JSON Data

kotlin

val gateway = CreditPlatformGatewayClient(baseUrl, tokenStore)
val result = gateway.createResponse(requestJson,
    GatewayRequestOptions(timeout = java.time.Duration.ofSeconds(60))) // requestJson 为 JsonNode

TypeScript 保留可扩展的 JSON 字段，Swift 返回 Data，Kotlin 返回 JsonNode；业务层按所选协议解码，避免把新增模型字段丢弃。金额保持十进制字符串。Gemini 方法接受模型 ID 或 models/ 前缀，并拒绝路径和查询参数注入。

中国大模型与公开目录

DeepSeek、Kimi、MiniMax 可按目录使用 Chat / Messages / Responses；智谱 GLM 当前支持 Chat / Messages，未实现 Responses。listPublicModels() 返回类型化的公开能力与费率，不读取或发送令牌；与 listModels() 按模型 ID 取交集后再选协议。完整的 TypeScript、Swift、Kotlin 示例见中国大模型接入。

TypeScript 的 ChatCompletion / ChatMessage / ChatToolCall 保留 reasoning_content、可空 content、工具调用和未知扩展字段。Swift Data 与 Kotlin JsonNode 也保留原始消息；多轮时不要只回传最终文本。0.3.0 新增目录方法，TypeScript 的默认 Chat 返回类型改为 ChatCompletion；自定义返回形状可继续传泛型参数。

流式、错误与升级

TypeScript 使用 streamChatCompletion、streamResponse、streamMessage 和 streamGeminiContent 消费 SSE。返回事件包含原始 data，请按协议处理终态和错误，见流式指南。Swift/Kotlin 本次只提供非流式调用。

从 0.1.0 升级时，原有非流式方法可继续使用；stream: true 在 JSON 方法中会明确报错，须迁移到流式方法。Swift/Kotlin 的 getUsage 为新增方法。网关不会自动刷新令牌或重试请求；对支持幂等的操作可通过请求选项传入 idempotencyKey，但这不代表任意接口都能安全重放。Responses 不支持 previous_response_id，媒体边界见协议说明。

从源码集成

TypeScript：在 sdk/typescript 运行 pnpm install --frozen-lockfile 和 pnpm build，再在应用中通过本地路径依赖或经过发布流程的包接入。
Swift：在 Xcode / SwiftPM 添加 sdk/swift 本地包；使用 Swift 6，最低 iOS 16 / macOS 13。
Kotlin：把 sdk/kotlin 作为 Gradle included build 引入，使用 Java 17；在 JVM 工作线程调用同步网络方法。

支付结果现在包含 client_params（Swift/Kotlin 为 clientParams），用于 client_sdk 支付模式；这些短期参数只用于本次结算，不应记录或持久化。Kotlin 解码忽略新增响应字段，并拒绝将 JSON 数字隐式转换为金额字符串。

官方 SDK 与 Embedded 集成 ​

TypeScript ​

Swift ​

Kotlin ​

网关 SDK 0.3.0 ​

中国大模型与公开目录 ​

流式、错误与升级 ​

从源码集成 ​