Generation Service
This page documents the OSS v1 generation surface tracked by #161.
Live Module Inventory
The generation story in the current repo spans a small set of stable entrypoints plus provider packages:
apps/server/api/src/app.module.ts- imports
BatchGenerationModule - imports the provider-facing integration modules used by generation flows
- imports
apps/server/api/src/services/batch-generation/batch-generation.module.ts- owns the batch-generation controller/service pair
- persists batch jobs on the cloud connection
apps/server/api/src/services/batch-generation/batch-generation.controller.ts- exposes the stable batch entrypoints under
batches - routes create/process/review operations into the service layer
- exposes the stable batch entrypoints under
apps/server/api/src/services/batch-generation/batch-generation.service.ts- builds batch plans
- delegates actual generation to
ContentGeneratorService
packages/actions/src/registry/source/index.ts- defines the canonical agent-visible generation tools
packages/actions/src/registry/tool-registry.ts- assigns generation tool categories and UI action cards
apps/server/api/src/services/agent-orchestrator/tools/agent-tool-executor.service.ts- dispatches generation tools to the internal media APIs
apps/server/workers/src/crons/model-watcher/cron.model-watcher.service.ts- discovers models from verified Replicate owners into an inactive review queue
packages/agent/src/utils/agent-generation-setup.util.ts- seeds default Unified Generation Setup values (aspect ratio, model, duration) for the Agent’s
GenerationActionCardreview — image/video only, with no Studio Look or Prompt Enhance sourcing (#4672)
- seeds default Unified Generation Setup values (aspect ratio, model, duration) for the Agent’s
Stable Generation Surface
For v1, the important point is not every experimental flow. It is the stable path:
- API/controller accepts a generation or batch request.
BatchGenerationServiceor another generation-facing service delegates into content generation.- Model/provider selection is resolved from reviewed model records in the shared registry.
- Provider adapters normalize generation results into one Genfeed-facing shape.
Stable generate_* Tool Surface
The v1 stable generation tools are the agent-facing tools that create generation work or route users into a generation review flow. Their metadata is defined in packages/actions/src/registry/source/index.ts and rendered through the canonical registry in packages/actions/src/registry/tool-registry.ts.
| Tool | Stable input contract | Execution path | Output contract |
|---|---|---|---|
generate_image | prompt, optional aspectRatio; attachments may become reference images | AgentToolExecutorService.generateImage -> POST /v1/images -> image provider selection | Content preview card with image ingredient id and gallery URL |
generate_video | prompt, optional aspectRatio, duration, imageUrl, audioUrl; image + audio selects avatar mode | AgentToolExecutorService.generateVideo -> POST /v1/videos -> video provider selection | Content preview card with video ingredient id and gallery URL |
generate_music | text, optional duration | AgentToolExecutorService.generateMusic -> POST /v1/musics -> music provider selection | Content preview card with music ingredient id and gallery URL |
generate_voice | text, voiceId | AgentToolExecutorService.generateVoice -> POST /v1/voices/generate -> voice provider selection | Content preview card with voice id or audio URL |
generate_content_batch | count, platforms, optional brandId, handle, dateRange, contentMix, style, topics | AgentToolExecutorService.generateContentBatch -> BatchGenerationService.createBatch | Batch id plus review queue/status actions |
generate_as_identity | text for the identity avatar to speak | AgentToolExecutorService.generateAsIdentity -> POST /v1/videos/avatar with useIdentity: true | Processing preview card for the avatar video generation |
These are the stable tool names callers should depend on for v1. Lower-level workflow categories such as generate-image, generate-video, and generate-music remain workflow-engine step categories, not public agent tool names.
Step 3 Module -> Provider -> Tool Map
| Layer | Files | Responsibility |
|---|---|---|
| Tool metadata | packages/actions/src/registry/source/index.ts, packages/actions/src/registry/tool-registry.ts | Defines tool names, parameters, categories, and UI action card types |
| Agent dispatch | apps/server/api/src/services/agent-orchestrator/tools/agent-tool-executor.service.ts | Converts tool calls into internal API requests and normalizes preview-card responses |
| Media APIs | /v1/images, /v1/videos, /v1/musics, /v1/voices/generate | Own request validation, model selection, credits, persistence, and completion polling |
| Skill execution | apps/server/api/src/services/skill-executor/* | Runs content skills such as image-generation through immutable canonical workflows |
| Provider access | apps/server/api/src/services/byok/* | Resolves organization BYOK keys before hosted fallback |
| Provider adapters | apps/server/api/src/services/integrations/* | Call Replicate, fal.ai, Leonardo, ElevenLabs, OpenRouter, and related provider surfaces |
| Registry/discovery | apps/server/workers/src/crons/model-watcher/cron.model-watcher.service.ts | Creates reviewed Replicate catalog candidates without auto-activation |
Dataflow
Representative V1 End-to-End Path
Two specs carry the representative media verification path:
apps/server/api/src/services/skill-executor/skill-executor.service.spec.tscovers workflow dispatchapps/server/api/src/services/skill-executor/handlers/image-generation.handler.spec.tscovers the representative image path
Both use mocked provider services so they run in CI without live credentials, but they keep the production service wiring.
SkillWorkflowService owns dispatch:
- every reviewed skill action and its immutable canonical workflow are registered on
SystemWorkflowRunner - executing a skill runs the selected canonical workflow and returns its
WorkflowExecutionprovenance - a slug outside the reviewed action catalog is rejected
ImageGenerationHandler owns the representative image path:
- organization BYOK resolution selects the provider for the active organization
- fal.ai, Leonardo, and Replicate model routing each receive the resolved server-side key and normalized image parameters
- a configured managed key routes generation through managed inference instead
- a provider capacity error fails over between Replicate and fal.ai rather than failing the draft
Run them with:
cd apps/server/api
TZ=UTC bunx vitest run --config vitest.config.ts src/services/skill-executorThis keeps the v1 proof end-to-end at the application boundary without making CI depend on external provider availability.
Explicit V1 Gaps
- The CI smoke path does not make a live fal.ai or Replicate request.
- It verifies one representative image path, not every media type or provider.
- Full provider billing, rate-limit, and callback behavior should stay covered by provider-specific tests and manual release checks.
V1 Boundary
This page documents the current registry and generation surface. It does not expand v1 to include every deferred model-registry or training-pipeline item by default.
For the OSS provider registry contract, see Provider Registry.