Official SDKs and Embedded integration

Official SDKs keep server credentials separate from client access. Use each package's release notes for current versions and installation commands.

The source release is 0.3.0, in sdk/typescript, sdk/swift, and sdk/kotlin. Integrate from source: the TypeScript package remains private. Do not assume npm/Maven publication or a Swift release tag exists.

Platform	App backend	Client self-service	Data API	Token interface
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()

Bundle ServerClient only into a trusted App backend. Browser and shared frontend packages use only a caller-provided TokenProvider.

Swift

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

Back CreditPlatformTokenStore with Keychain on iOS. Never ship an AppClient secret in the app bundle.

Kotlin

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

The Kotlin package targets Java 17 JVM through java.net.http; use host-appropriate secure storage, not an assumed Android networking runtime. On every platform, bind the Application code during client construction; business callers must not supply another Application or user ID per request.

SDK errors should contain only an HTTP status and safe error code. Do not append full responses, request bodies, or credentials in wrappers.

Gateway SDK 0.3.0

All three platforms use the same method names for these non-streaming operations. Set baseUrl / baseURL to the data API origin without /v1 or /v1beta; the SDK supplies the complete paths. This differs from the OpenAI SDK configuration.

Method	Endpoint
listPublicModels	GET /api/v1/public/models (unauthenticated)
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

Gateway clients accept an AICredits Direct API key (sk-) or Embedded token (axt_) through the token interface. Keep Direct keys on trusted backends; browsers and devices use short-lived tokens exchanged by the app backend. Embedded clients still accept only axt_ tokens for self-service operations.

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

// Trusted Node.js backend; devices use their own short-lived 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) },
)

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

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

TypeScript preserves extensible JSON fields, Swift returns Data, and Kotlin returns JsonNode. Decode according to the selected protocol without discarding new model fields. Monetary values remain decimal strings. Gemini methods accept an ID or a models/ prefix and reject path/query injection.

Streaming, errors, and migration

TypeScript provides streamChatCompletion, streamResponse, streamMessage, and streamGeminiContent for SSE. Events contain raw data; handle terminal and error events according to the streaming guide. Swift/Kotlin provide non-streaming calls in this release.

Existing non-streaming methods remain usable when upgrading from 0.1.0. JSON methods now reject stream: true; migrate those calls to streaming methods. Swift/Kotlin gain getUsage. Gateway clients never refresh tokens or retry automatically. Supply idempotencyKey in request options for operations that support it; the header does not make every operation safe to replay. Responses does not support previous_response_id; see protocol limits for media boundaries.

Source installation

• TypeScript: run pnpm install --frozen-lockfile and pnpm build in sdk/typescript, then add a local path dependency or a package distributed through your release process.
• Swift: add sdk/swift as a local Xcode / SwiftPM package. Requires Swift 6 and iOS 16 / macOS 13 or later.
• Kotlin: include sdk/kotlin in a Gradle composite build with Java 17. Run its synchronous network calls on a JVM worker thread.

Payment results now include client_params (clientParams in Swift/Kotlin) for client_sdk checkout. Use these short-lived parameters only for the current checkout; never log or persist them. Kotlin ignores newly added response fields and rejects implicit JSON number-to-money-string conversion.

Chinese models and the public catalog

DeepSeek, Kimi and MiniMax have catalog-dependent Chat / Messages / Responses paths; Zhipu GLM currently has Chat / Messages and no Responses path. listPublicModels() returns typed public capabilities and rates without reading or sending a token. Intersect IDs with listModels() before selecting a protocol. See Chinese model integration for TypeScript, Swift and Kotlin examples.

TypeScript ChatCompletion, ChatMessage and ChatToolCall retain reasoning_content, nullable content, tools and unknown extensions. Swift Data and Kotlin JsonNode also preserve complete messages. Version 0.3.0 adds discovery and changes the default TypeScript Chat return type to ChatCompletion; custom shapes can still use the generic parameter.