PR #62457: atlascloud: add Atlas Cloud video generation provider plugin

• Repository: openclaw/openclaw
• Author: divolleggett
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/62457

Description (problem / solution / changelog)

Summary

• Problem: OpenClaw's video generation provider list does not include Atlas Cloud, an aggregation platform that exposes 100+ models from Kling / Veo / Seedance / Wan / Vidu / Sora / Hailuo and others through a single unified API. Users who want any of those models today have to onboard each upstream provider individually or build their own integration.
• Why it matters: Atlas Cloud is a fal-style aggregator, so a single plugin unlocks a very broad set of models without expanding OpenClaw's per-provider auth surface.
• What changed: New extensions/atlascloud plugin (one provider, one VideoGenerationProvider), one new entry in the shared extensions/video-generation-providers.live.test.ts CASES array (mirroring the existing 11 providers), and one new alphabetical label entry in .github/labeler.yml.
• What did NOT change (scope boundary): No src/ changes, no other extensions touched, no CODEOWNERS-protected paths, no new SDK seams. The plugin only consumes existing public openclaw/plugin-sdk/* barrels.

Tracked under #62456 (proposal issue, filed because openclaw/openclaw Discussions are disabled per hasDiscussionsEnabled: false).

Change Type (select all)

• Feature
• Bug fix
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Integrations
• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related #62456

Root Cause

N/A — this is a new feature, not a bug fix.

Regression Test Plan

N/A — new surface. New tests added in this PR (see Evidence).

User-visible / Behavior Changes

• New provider id atlascloud (aliases: atlas-cloud, atlas) registered with the plugin SDK.
• New auth method --atlascloud-api-key / ATLASCLOUD_API_KEY env var.
• New default video model when the user has no agents.defaults.videoGenerationModel set: atlascloud/google/veo3.1-fast/text-to-video. Existing user defaults are not overwritten.
• New optional config key models.providers.atlascloud.extraParams[modelId or modelPrefix] for per-model field passthrough (cfg_scale, camera_fixed, movement_amplitude, shot_type, etc.) without needing to extend OpenClaw's generic VideoGenerationRequest.
• Input image / video buffers ≥ 2 MiB are auto-uploaded via POST /api/v1/model/uploadMedia and replaced with the returned download_url before submit. Smaller buffers stay inline as base64 data URLs (avoids extra round trip and stays under per-model size limits).

Diagram

User: pnpm openclaw video generate --provider atlascloud --model <id> --image foo.jpg --prompt ...
  │
  ▼
generateVideo(req):
  resolve API key (Bearer <ATLASCLOUD_API_KEY>)
  ─► prepareAtlasCloudInputs(req): walk inputImages/inputVideos
       ├─ asset.url present  → keep as-is
       ├─ asset.buffer < 2 MiB → keep, will inline as base64 in body
       └─ asset.buffer ≥ 2 MiB → POST /api/v1/model/uploadMedia → asset.url = download_url
  ─► buildAtlasCloudVideoBody(req): resolve per-model schema, map fields family-aware
       ├─ aspect_ratio (Veo) vs ratio (Wan 2.7) vs size with * separator (Wan 2.6) vs size with x (Sora)
       ├─ generate_audio (Veo/Seedance/Vidu) vs sound (Kling)
       ├─ image (single) vs images[] (Vidu reference)
       ├─ last_image (Veo) vs end_image (Kling) for end-frame
       ├─ videos[] (Wan v2v)
       └─ merge per-model defaults + user extraParams (highest priority)
  ─► POST /api/v1/model/generateVideo → prediction id
  ─► poll urls.get (preferred) → /result/{id} → /prediction/{id}
       until status in {completed, succeeded}
  ─► download outputs[0] → return GeneratedVideoAsset

Security Impact

• New permissions/capabilities? No. Uses the existing createProviderApiKeyAuthMethod SDK helper.
• Secrets/tokens handling changed? No. The plugin only reads ATLASCLOUD_API_KEY via resolveApiKeyForProvider, which is the same path every other API-key plugin uses.
• New/changed network calls? Yes. Outbound to:
  • https://api.atlascloud.ai/api/v1/model/generateVideo (POST submit)
  • https://api.atlascloud.ai/api/v1/model/uploadMedia (POST multipart, only when an input buffer ≥ 2 MiB needs uploading)
  • https://api.atlascloud.ai/api/v1/model/result/{id} and /prediction/{id} (GET poll)
  • The signed download_url returned by submit, which lives on volces.com (Volcano TOS signed URL, 24h expiry) All requests go through fetchWithSsrFGuard from openclaw/plugin-sdk/ssrf-runtime (not raw fetch), so they participate in the standard SSRF guard, dispatcher policy, and audit context machinery.
• Command/tool execution surface changed? No.
• Data access scope changed? No. The plugin reads input assets the user explicitly passes to video generate and writes generated bytes to the standard GeneratedVideoAsset return shape.

Repro + Verification

Environment

• OS: macOS 15
• Runtime: Node 22.22.1
• Provider/model: bytedance/seedance-v1.5-pro/text-to-video, bytedance/seedance-v1.5-pro/image-to-video, plus 65 other model overrides registered statically
• Channel: N/A (provider plugin)
• Relevant config (redacted):

  {
    "models": { "providers": { "atlascloud": { "extraParams": { "kwaivgi/kling-v3.0-pro/": { "cfg_scale": 0.7 } } } } }
  }

Steps

1. pnpm openclaw login --provider atlascloud --atlascloud-api-key $ATLASCLOUD_API_KEY
2. pnpm openclaw video generate --provider atlascloud --model bytedance/seedance-v1.5-pro/text-to-video --prompt "a calm sunrise over mountains" --output /tmp/out.mp4
3. (Image-to-video) pnpm openclaw video generate --provider atlascloud --model bytedance/seedance-v1.5-pro/image-to-video --image ./photo.jpg --prompt "subtle camera push-in" --output /tmp/out-i2v.mp4

Expected

• Submit returns a prediction id, plugin polls until status is completed or succeeded, downloads outputs[0], returns a GeneratedVideoAsset with mimeType: video/mp4.

Actual

• Verified live (see Evidence).

Evidence

• Offline body builder unit tests: 14-case vitest file extensions/atlascloud/video-generation-provider.test.ts covering Veo / Kling / Seedance / Wan / Vidu / Sora field name mapping, end-frame field difference (last_image vs end_image), size separator conversion, mode-required-input checks, per-model defaults, user extraParams exact + prefix override, and unregistered-model fallback to family baseline.
• Live test wiring: extensions/video-generation-providers.live.test.ts updated to include the atlascloud entry in the shared CASES array, alphabetically between alibaba and byteplus. This is the same pattern the existing 11 video providers use.
• Real Atlas Cloud API verification:
  • T2V live: Submit bytedance/seedance-v1.5-pro/text-to-video → prediction id → poll returns status: completed after ~43s → output URL is a real signed Volcano TOS mp4.
  • Upload live: POST a 320×320 PNG (1960 bytes) to /api/v1/model/uploadMedia → response includes a public oss-accelerate-overseas.aliyuncs.com download URL.
  • I2V end-to-end live: Submit bytedance/seedance-v1.5-pro/image-to-video with the uploaded URL → poll returns status: completed after ~60s → output URL is a real signed Volcano TOS mp4.
  • Failure path live: With an intentionally too-small (1×1) input image, Atlas Cloud returned status: failed with a clean data.error field (expected the width to be at least 300px, but received a 1x1px image). The plugin's poll loop now prefers data.error over the top-level message field, because on failure message wraps the entire upstream JSON body and is not human-readable.

Human Verification

• Verified scenarios:
  • 14/14 offline body builder unit tests pass against the real model-schemas.ts table.
  • Real T2V end-to-end against Atlas Cloud (Seedance v1.5 Pro).
  • Real upload-media end-to-end (320×320 PNG, returns OSS download URL).
  • Real I2V end-to-end (Seedance v1.5 Pro, uploaded image → completed mp4).
  • Real failure path (1×1 image is rejected upstream and surfaced cleanly).
• Edge cases checked:
  • Per-model schema overrides for Veo (last_image), Kling (end_image, sound instead of generate_audio), Wan 2.6 (size with *), Wan 2.7 (ratio instead of aspect_ratio, uppercase 1080P), Sora (size with x), Vidu (multi-image images[]).
  • User extraParams with both exact key and prefix/ key (longest prefix wins, exact overrides prefix).
  • Unregistered model id fallback to family baseline (e.g. a hypothetical minimax/hailuo-99/text-to-video).

Compatibility / Migration

• Backward compatible? Yes. New plugin, no existing config keys removed or repurposed.
• Config/env changes? Yes (new optional). New env var ATLASCLOUD_API_KEY, new optional config block models.providers.atlascloud.{baseUrl,extraParams}. Default video model is only set when the user has no agents.defaults.videoGenerationModel configured.
• Migration needed? No.

Risks and Mitigations

• Risk: Unverified per-model schemas (53 of the 67 entries) could have wrong field names if Atlas Cloud changes a model.
  • Mitigation: The pure body builder lives behind family baselines plus per-model overrides. Users can override any field via extraParams[modelId or prefix] without code changes. A CI refresher script can periodically diff against the real /api/v1/models/{id} endpoint and open a follow-up PR.
• Risk: The auto-upload threshold (2 MiB) is a heuristic.
  • Mitigation: Below threshold, the plugin still works because Atlas Cloud accepts both base64 data URLs and public URLs in image fields (verified against the documented per-model schemas for Hailuo, Vidu, Kling). Above threshold, the upload path is the documented Atlas Cloud /uploadMedia endpoint with the multipart shape from the official AtlasCloudAI/mcp-server reference implementation.
• Risk: The shared file extensions/video-generation-providers.live.test.ts is touched.
  • Mitigation: The change is one new entry inserted alphabetically in the existing CASES array, identical in shape to the 11 sibling entries. No logic added; no rerun semantics changed.

Changed files

• .github/labeler.yml (modified, +4/-0)
• extensions/atlascloud/body-builder.ts (added, +172/-0)
• extensions/atlascloud/index.ts (added, +51/-0)
• extensions/atlascloud/model-schemas.ts (added, +896/-0)
• extensions/atlascloud/onboard.ts (added, +25/-0)
• extensions/atlascloud/openclaw.plugin.json (added, +32/-0)
• extensions/atlascloud/package.json (added, +15/-0)
• extensions/atlascloud/tsconfig.json (added, +12/-0)
• extensions/atlascloud/video-generation-provider.test.ts (added, +190/-0)
• extensions/atlascloud/video-generation-provider.ts (added, +453/-0)
• extensions/video-generation-providers.live.test.ts (modified, +7/-0)