AI Features Overview

Overview

NimBuild Starter integrates with Volcano Engine (ByteDance's Doubao API) for AI capabilities:

Configuration

All AI integrations require a Volcano Engine API key:

VOLCANO_ENGINE_API_KEY="your-api-key"
VOLCANO_ENGINE_API_URL="https://ark.cn-beijing.volces.com/api/v3"

Architecture

The provider adapter lives in extensions/ai/volcano-engine/:

extensions/ai/volcano-engine/
├── config.ts    # API configuration
├── chat.ts      # Chat completion + streaming
├── image.ts     # Image generation
├── video.ts     # Video generation (async)
└── types.ts     # TypeScript interfaces

Feature-owned server workflows live in features/demo/server/. They validate inputs, deduct credits, call the provider adapter, persist chat or generation history through modules/db, and mirror generated media through extensions/storage/r2 when storage is configured.

Credit Integration

Every AI operation follows the deduct-first, refund-on-failure pattern:

1. Check if user has enough credits
2. Deduct credits from balance
3. Call AI API
4. If API fails, refund credits automatically

Replacing the AI Provider

To switch from Volcano Engine to OpenAI, Anthropic, or another provider:

1. Add a new adapter under extensions/ai/your-provider/
2. Update the server workflows in features/demo/server/
3. Update environment variables
4. Adjust model configuration
5. Keep the same credit deduction and refund-on-failure pattern