elizaos--eliza/plugins/plugin-elizacloud

@elizaos/plugin-elizacloud

Eliza Cloud plugin for elizaOS agents. The TypeScript package is backed by @elizaos/cloud-sdk, so runtime Cloud API calls, auth helpers, route wrappers, TTS, STT, image generation, containers, and gateway relay code use the same SDK surface as other Eliza Cloud clients.

Installation

npm install @elizaos/plugin-elizacloud
# or
bun add @elizaos/plugin-elizacloud

Register the plugin with your agent runtime:

import { elizaOSCloudPlugin } from "@elizaos/plugin-elizacloud";

const agent = new Agent({
  plugins: [elizaOSCloudPlugin],
});

SDK Contract

The TypeScript package has a hard dependency on @elizaos/cloud-sdk. Development checkouts resolve it with workspace:*; published packages are expected to consume the npm-published SDK version.

Runtime code must not build direct Eliza Cloud HTTP calls by hand. Use the SDK helpers in src/utils/sdk-client.ts:

Helper	Use
createCloudApiClient(runtime)	API-base requests such as /responses, /embeddings, /models, auth validation, containers, and relay JSON endpoints
createCloudApiClient(runtime, true)	Embedding requests that may use ELIZAOS_CLOUD_EMBEDDING_URL / ELIZAOS_CLOUD_EMBEDDING_API_KEY
createElizaCloudClient(runtime)	High-level SDK helpers and generated client.routes.* wrappers
src/utils/cloud-api.ts	Backwards-compatible re-export of SDK classes and types

ELIZAOS_CLOUD_BASE_URL remains the API base URL and defaults to https://elizacloud.ai/api/v1. createElizaCloudClient derives the site root from that API URL when generated SDK route wrappers need /api/v1/... paths.

src/providers/openai.ts is the one intentional transport adapter that passes the configured base URL to the Vercel AI SDK's OpenAI-compatible client. It is not a hand-rolled Cloud API fetch path.

Runtime Coverage

Plugin capability	SDK path
Text generation (TEXT_NANO, TEXT_SMALL, TEXT_MEDIUM, TEXT_LARGE, TEXT_MEGA, response handler, planner)	CloudApiClient.requestRaw("POST", "/responses", ...)
Structured object generation	CloudApiClient.requestRaw("POST", "/responses", ...)
Research generation	CloudApiClient.requestRaw("POST", "/responses", ...)
Text embeddings	CloudApiClient.requestRaw("POST", "/embeddings", ...)
Image generation	ElizaCloudClient.generateImage(...)
Image description	generated SDK route client.routes.postApiV1ChatCompletionsRaw(...)
Text-to-speech	generated SDK route client.routes.postApiV1VoiceTts(...)
Audio transcription	generated SDK route client.routes.postApiV1VoiceSttRaw(...)
Model registry and credit status	CloudApiClient
Device auth and API-key validation	CloudApiClient
Cloud containers	CloudApiClient supplied by CloudAuthService
Managed gateway relay	CloudApiClient
Credits, app credits, and hosted checkout	ElizaCloudClient.createCreditsCheckout(...), getAppCreditsBalance(...), createAppCreditsCheckout(...)
Agent/app charge requests	ElizaCloudClient.createAppCharge(...), createAppChargeCheckout(...)
x402 payment requests and settlement	ElizaCloudClient.createX402PaymentRequest(...), getX402Supported(...), settleX402PaymentRequest(...)
Affiliate links and creator payouts	createAffiliateCode(...), linkAffiliateCode(...), getAppEarnings(...), withdrawAppEarnings(...), createRedemption(...)

The only remaining runtime-adjacent fetch() usage is in the plugin test block for downloading a public audio fixture. It is not an Eliza Cloud API call.

Payments And Monetization

The plugin exposes one local route family for Cloud money flows: /api/cloud/billing/*. It forwards to the authenticated Cloud API using the same Cloud key as the rest of the plugin, so app UIs and agents do not need to handle Cloud credentials directly.

Supported local aliases:

Local route	Cloud route
/api/cloud/billing/credits/*	/api/v1/credits/*
/api/cloud/billing/app-credits/*	/api/v1/app-credits/*
/api/cloud/billing/x402/*	/api/v1/x402/*
/api/cloud/billing/apps/{appId}/charges/*	/api/v1/apps/{appId}/charges/*
/api/cloud/billing/apps/{appId}/earnings/*	/api/v1/apps/{appId}/earnings/*
/api/cloud/billing/apps/{appId}/monetization	/api/v1/apps/{appId}/monetization
/api/cloud/billing/affiliates/*	/api/v1/affiliates/*
/api/cloud/billing/redemptions/*	/api/v1/redemptions/*

Agent-initiated charges should use app charge requests for Stripe/OxaPay credit checkout or x402 payment requests for direct crypto settlement. Both request types accept callback channel metadata, so successful or failed payment events can be written back into the room where the charge was initiated.

Configuration

Get an API key from https://www.elizacloud.ai/dashboard/api-keys.

Setting	Description	Default
ELIZAOS_CLOUD_API_KEY	API key used for authenticated Cloud requests	Required
ELIZAOS_CLOUD_BASE_URL	Eliza Cloud API base URL	https://elizacloud.ai/api/v1
ELIZAOS_CLOUD_ENABLED	Enables container provisioning, device auth, bridge, and backup services	false
ELIZAOS_CLOUD_NANO_MODEL	Nano/cheapest model override	NANO_MODEL or gemma-4-31b
ELIZAOS_CLOUD_SMALL_MODEL	Small/fast model override	SMALL_MODEL or gemma-4-31b
ELIZAOS_CLOUD_MEDIUM_MODEL	Medium planning model override	MEDIUM_MODEL or small model
ELIZAOS_CLOUD_LARGE_MODEL	Large model override	LARGE_MODEL or gemma-4-31b
ELIZAOS_CLOUD_MEGA_MODEL	Mega model override	MEGA_MODEL or large model
ELIZAOS_CLOUD_RESPONSE_HANDLER_MODEL	Response handler model override	small model
ELIZAOS_CLOUD_ACTION_PLANNER_MODEL	Action planner model override	large model
ELIZAOS_CLOUD_RESEARCH_MODEL	Research model override	large model
ELIZAOS_CLOUD_EMBEDDING_MODEL	Embedding model	text-embedding-3-small
ELIZAOS_CLOUD_EMBEDDING_URL	Optional custom embedding API base URL	unset
ELIZAOS_CLOUD_EMBEDDING_API_KEY	Optional custom embedding API key	ELIZAOS_CLOUD_API_KEY
ELIZAOS_CLOUD_EMBEDDING_DIMENSIONS	Embedding vector size	1536
ELIZAOS_CLOUD_IMAGE_DESCRIPTION_MODEL	Vision model used for image descriptions	gpt-5.4-mini
ELIZAOS_CLOUD_IMAGE_DESCRIPTION_MAX_TOKENS	Max image-description response tokens	8192
ELIZAOS_CLOUD_IMAGE_GENERATION_MODEL	Image generation model override	google/nano-banana-2/text-to-image
ELIZAOS_CLOUD_TTS_MODEL	Text-to-speech model	gpt-5-mini-tts
ELIZAOS_CLOUD_USE_STT	Per-service opt-in for Cloud STT when ELIZAOS_CLOUD_ENABLED is unset (capability-only mode)	unset
ELIZAOS_CLOUD_STT_TIMEOUT_MS	Cloud STT request timeout	60000
ELIZAOS_CLOUD_EXPERIMENTAL_TELEMETRY	Enables experimental telemetry metadata	false

Browser builds must not receive secrets directly. Use ELIZAOS_CLOUD_BROWSER_BASE_URL and ELIZAOS_CLOUD_BROWSER_EMBEDDING_URL for browser-only proxy endpoints.

Usage Examples

import { ModelType } from "@elizaos/core";

const text = await runtime.useModel(ModelType.TEXT_LARGE, {
  prompt: "Summarize the current agent state.",
});

// Structured output: route through TEXT_* with `responseSchema` (native tool calling).
const structured = await runtime.useModel(ModelType.TEXT_LARGE, {
  prompt: "Return a JSON user profile with name and role.",
  responseSchema: {
    type: "object",
    properties: { name: { type: "string" }, role: { type: "string" } },
    required: ["name", "role"],
  },
});

const embedding = await runtime.useModel(ModelType.TEXT_EMBEDDING, {
  text: "Hello, world!",
});

const speech = await runtime.useModel(ModelType.TEXT_TO_SPEECH, {
  text: "Cloud text to speech is active.",
});

// STT: accepts Buffer/Blob/File bytes, an http(s) audio URL string, or
// core TranscriptionParams ({ audioUrl }). URL fetches go through the
// SSRF guard. Requires ELIZAOS_CLOUD_ENABLED=true or ELIZAOS_CLOUD_USE_STT=true.
const transcript = await runtime.useModel(ModelType.TRANSCRIPTION, audioBuffer);

Adding Cloud Calls

1. Prefer an existing high-level SDK method when one exists.
2. Otherwise use a generated createElizaCloudClient(runtime).routes.* wrapper.
3. Use createCloudApiClient(runtime) for raw API-base endpoints that do not yet have a generated wrapper.
4. Keep all Eliza Cloud API auth/header/base-URL behavior inside the SDK helper layer.
5. Do not add direct fetch() calls for Eliza Cloud API routes in runtime code.

When the Cloud API adds or changes public routes, update the SDK first (see the Development section below), then update this plugin to consume the new SDK route or helper.

Development

bun run --cwd plugins/plugin-elizacloud typecheck
bun run --cwd plugins/plugin-elizacloud test
bun run --cwd plugins/plugin-elizacloud build

When the Cloud API adds or changes public routes, update @elizaos/cloud-sdk first, then update this plugin to consume the new SDK route or helper:

bun run --cwd packages/cloud/sdk build
bun run --cwd packages/cloud/sdk typecheck
bun run --cwd packages/cloud/sdk test

Publishing

This plugin is published to npm as @elizaos/plugin-elizacloud. Publishing requires a compatible @elizaos/cloud-sdk release because the plugin depends on it directly.

License

MIT