If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/AIDC-AI/Pixelle-Video shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 13 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 54% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live AIDC-AI/Pixelle-Video repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/AIDC-AI/Pixelle-Video.

What it runs against: a local clone of AIDC-AI/Pixelle-Video — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in AIDC-AI/Pixelle-Video | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of AIDC-AI/Pixelle-Video. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/AIDC-AI/Pixelle-Video.git
#   cd Pixelle-Video
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of AIDC-AI/Pixelle-Video and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "AIDC-AI/Pixelle-Video(\\.git)?\\b" \\
  && ok "origin remote is AIDC-AI/Pixelle-Video" \\
  || miss "origin remote is not AIDC-AI/Pixelle-Video (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "api/app.py" \\
  && ok "api/app.py" \\
  || miss "missing critical file: api/app.py"
test -f "api/config.py" \\
  && ok "api/config.py" \\
  || miss "missing critical file: api/config.py"
test -f "api/tasks/manager.py" \\
  && ok "api/tasks/manager.py" \\
  || miss "missing critical file: api/tasks/manager.py"
test -f "api/routers/video.py" \\
  && ok "api/routers/video.py" \\
  || miss "missing critical file: api/routers/video.py"
test -f "api/schemas/base.py" \\
  && ok "api/schemas/base.py" \\
  || miss "missing critical file: api/schemas/base.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/AIDC-AI/Pixelle-Video"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Pixelle-Video is an AI-powered automated short-video generation engine that transforms a user-provided topic into a complete video with zero manual editing. Given only a theme, it orchestrates AI-driven scriptwriting (GPT/Qwen/DeepSeek), image/video generation (FLUX, WAN 2.1 via ComfyUI), TTS synthesis (Edge-TTS, Index-TTS, ChatTTS), background music insertion, and final video composition—all through a FastAPI backend and web UI. Monolithic FastAPI application: api/app.py is the entry point, api/routers/ (content.py, video.py, image.py, llm.py, tts.py, etc.) handle distinct processing stages, api/schemas/ define request/response contracts, api/tasks/manager.py orchestrates async job execution, and a separate frontend (HTML 233K lines, likely in frontend/ or web/) communicates via REST. ComfyUI workflows are stored as templates and invoked via API calls.

Content creators with zero video editing experience, small media teams, and automation enthusiasts who want to produce short-form video content (YouTube Shorts, TikTok, Bilibili) without hiring editors or learning video composition; also developers who want to extend video generation pipelines through ComfyUI workflows and custom API integrations.

Actively developed and production-ready: the repo shows frequent recent commits (updates through January 2026), a mature web UI, Windows packaging, comprehensive documentation in docs/ and docs/en/, and GitHub Actions CI/CD for docs. However, it is a single-maintainer project (AIDC-AI org) with limited public test coverage visible in the file structure.

Moderate risk: the project depends heavily on external AI services (OpenAI, Alibaba Qwen, DeepSeek, RunningHub, ComfyUI APIs) meaning API rate limits and service outages could block users; no visible pytest suite indicates testing gaps; dependency on Python 777K lines and Docker suggests complex environment setup; single maintainer increases bus-factor risk.

Recent features (Jan 2026): motion transfer module (upload reference video + image), digital human anchor pipeline, image-to-video generation, multi-language TTS support, RunningHub 48G GPU access, ComfyUI API key auth, Nano Banana model support, template parameter customization, and history page for batch video task management.

git clone https://github.com/AIDC-AI/Pixelle-Video.git && cd Pixelle-Video && pip install -r requirements.txt && cp config.example.yaml config.yaml && python -m uvicorn api.app:app --reload (or use docker-compose up for containerized setup).

Daily commands: Option 1 (local): python -m uvicorn api.app:app --reload (requires config.yaml). Option 2 (Docker): docker-compose up (see docker-compose.yml, Dockerfile, docker-start.sh). Option 3 (dev container): Open in VS Code with .devcontainer/devcontainer.json and use postCreate.sh + postStart.sh hooks.

• api/app.py — FastAPI application entry point that initializes all routers, middleware, and configuration—essential for understanding the entire API structure
• api/config.py — Configuration management and validation—all deployments and feature toggles depend on this singleton
• api/tasks/manager.py — Task queue and async job management core—handles video generation pipeline orchestration
• api/routers/video.py — Primary video generation API endpoint—the main entry point for end-to-end video creation workflows
• api/schemas/base.py — Base request/response schemas—all API contracts and data validation inherit from here
• Dockerfile — Production container definition—required for understanding deployment, dependencies, and runtime environment
• docker-compose.yml — Local development and deployment orchestration—defines service interdependencies and configuration

Add a New API Endpoint

1. Create a new router file in api/routers/ following existing endpoint patterns (e.g., video.py). Use FastAPI's APIRouter with path parameters and dependency injection from api/dependencies.py. (api/routers/your_domain.py)
2. Define request/response Pydantic models in api/schemas/ inheriting from base schemas to ensure consistent error handling and documentation. (api/schemas/your_domain.py)
3. Register the new router in api/app.py using app.include_router() with an appropriate API prefix (e.g., /api/v1/your-domain). (api/app.py)
4. If the endpoint requires long-running operations, add task submission logic via api/tasks/manager.py and track status using models in api/tasks/models.py. (api/tasks/manager.py)

Add a New Video Processing Step to the Pipeline

1. Create or extend a service module in pixelle_video/services/ (not shown but inferred from architecture) that implements the processing logic (e.g., frame blending, text overlay, effects). (pixelle_video/services/processing.py)
2. Update the task manager pipeline in api/tasks/manager.py to integrate the new processing step into the orchestration flow, defining input/output contracts and error handling. (api/tasks/manager.py)
3. Extend the video endpoint in api/routers/video.py to expose new parameters for the processing step in the request body. (api/routers/video.py)
4. Add corresponding schemas to api/schemas/video.py to document the new parameters and validate input. (api/schemas/video.py)

Add a New Template or Style Option

1. Define a new template configuration object in api/schemas/content.py with style-specific parameters (colors, fonts, layout). (api/schemas/content.py)
2. Store template assets (images, fonts) in a designated resources directory (referenced in docs but not explicitly listed) and register them in api/routers/resources.py to expose via API. (api/routers/resources.py)
3. Update configuration in api/config.py to include the new template in available styles enumeration. (api/config.py)
4. Extend the content creation endpoint in api/routers/content.py to handle the new template style selection and pass it through to the task pipeline. (api/routers/content.py)

Add a New LLM or External Service Integration

1. Add configuration parameters to api/config.py for API keys, endpoints, and provider-specific settings. (api/config.py)
2. Create request/response schemas in api/schemas/llm.py for the new service's interface. (api/schemas/llm.py)
3. Add or extend the LLM endpoint in api/routers/llm.py to route requests to the new service with appropriate error handling. (api/routers/llm.py)
4. If integration requires persistent state or retry logic, update the task manager in api/tasks/manager.py to handle failures gracefully. (api/tasks/manager.py)

• FastAPI — Modern async Python framework with built-in OpenAPI documentation, dependency injection, and high performance—ideal for video processing microservices with long-running tasks
• Pydantic — Type-safe request/response validation and serialization with zero-cost abstractions; automatic OpenAPI schema generation for API documentation
• Docker & Docker Compose — Containerization ensures reproducible builds across environments; compose simplifies multi-service orchestration (API, workers, databases) in development and production
• Python (asyncio) — Async I/O enables concurrent processing of video jobs without blocking; ideal for I/O-bound operations like file uploads, API calls, and frame rendering
• YAML Configuration — Human-readable configuration for feature flags, model paths, and deployment parameters—easier than environment variables for complex nested structures

• Async task queue over synchronous processing

  • Why: Video generation is CPU/I/O intensive and can take minutes; async queuing allows the API to respond immediately and serve other requests
  • Consequence: Requires task state persistence and polling-based status checks; adds operational complexity but dramatically improves user experience and resource utilization

• Modular router

  • Why: undefined
  • Consequence: undefined

1. config.yaml must be manually copied from config.example.yaml and populated with real API keys (OpenAI, Qwen, etc.) or the app will fail silently or throw 401/403 errors. 2. ComfyUI must be running separately (either locally or accessed via remote URL specified in config) or image/video generation endpoints will timeout. 3. External API rate limits (RunningHub, OpenAI, etc.) are not visible in code; production use may hit quotas. 4. TTS service stability issues mentioned in changelog (fixed by pinning edge-tts version) suggest version conflicts—check requirements.txt for pinned versions. 5. No visible test suite; adding tests requires understanding both FastAPI patterns and the orchestration flow across routers. 6. File paths in video output are platform-dependent (mentioned in changelog as a past bug); cross-platform path handling uses pathlib (verify in routers).

• Async Task Queue & Job Management — api/tasks/manager.py handles concurrent video generation; understanding task scheduling, polling, and state persistence is critical for adding features like job cancellation, progress webhooks, or distributed task workers
• ComfyUI Workflow Orchestration — Pixelle-Video abstracts AI model calls (image, video, upscaling) through ComfyUI node graphs; you must understand how workflows are parameterized, queued, and results are polled to modify or add new generation steps
• LLM API Abstraction & Structured Output — api/routers/llm.py wraps multiple LLM providers (OpenAI, Qwen, DeepSeek) with a common interface; changelog mentions 'optimizing LLM structured data logic,' implying JSON schema parsing and validation across model variants
• Text-to-Speech Engine Abstraction — api/routers/tts.py supports Edge-TTS, Index-TTS, ChatTTS with different latency/quality profiles; selecting and switching engines requires understanding callback timing, stream buffering, and output format negotiation
• Template-Driven Parameter Customization — Recent changelog mentions 'template self-define parameter support'; implies a configuration abstraction layer where workflows and pipelines are parameterized for user customization without code changes
• Pydantic Schema Validation — api/schemas/ uses Pydantic for request/response contracts; understanding Pydantic validators, custom types, and error responses is essential for modifying or extending API contracts safely
• Cross-Platform File Path Handling — Changelog mentions a past bug: 'video generation API returns URL path processing, supports cross-platform compatibility'; implies pathlib usage; important when deploying on Linux vs Windows or debugging file-not-found errors

• ylluminate/ComfyUI — Pixelle-Video orchestrates image/video generation by calling ComfyUI APIs; understanding ComfyUI workflow architecture is essential for extending model pipelines
• descript/hypercorn — Alternative async Python web server if switching from uvicorn; both are ASGI servers suitable for FastAPI apps with high concurrency demands
• openai/openai-python — Official OpenAI SDK used by api/routers/llm.py for GPT integration; reference for handling streaming responses and structured output
• riffusion/riffusion-run-locally — Similar local-first AI audio/music generation project; shows patterns for bundling external ML models and avoiding external API dependencies
• oobabooga/text-generation-webui — Alternative to Ollama for local LLM inference; relevant if Pixelle-Video users want offline script generation without cloud APIs

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for api/tasks/manager.py task lifecycle

The api/tasks/manager.py module handles critical task management logic for the video generation pipeline, but there are no visible test files in the repo structure. This is high-value because task management is central to the async video processing workflow. Tests should cover task creation, status tracking, error handling, and cleanup.

• [ ] Create tests/api/tasks/test_manager.py with unit tests for TaskManager class methods
• [ ] Test task creation, retrieval, update, and deletion operations
• [ ] Test status transitions and error state handling
• [ ] Add tests for concurrent task handling and race conditions
• [ ] Verify cleanup of completed/failed tasks

Add GitHub Actions workflow for automated API integration tests

The repo has docs.yml workflow but no CI for running API tests. Given the fastapi-based architecture with multiple routers (content, video, frame, image, tts, llm), an automated test pipeline would catch regressions. This is especially important since the video generation involves external dependencies (LLM, TTS services).

• [ ] Create .github/workflows/api-tests.yml with Python test job
• [ ] Use pytest to run tests in tests/api/routers/ for each router endpoint
• [ ] Mock external service dependencies (LLM, TTS) using responses/pytest-mock
• [ ] Configure matrix testing for Python versions and key dependency versions
• [ ] Add coverage reporting and set minimum coverage threshold

Implement structured logging and observability in api/app.py and routers

The API lacks visible logging/observability configuration despite handling complex video generation tasks that can fail at multiple stages. Given the distributed nature (tasks, external APIs), adding structured logging (JSON format) with request tracing IDs would greatly improve debuggability for users and developers. This is evident from the FAQ docs mentioning troubleshooting.

• [ ] Add python-json-logger or similar to api/app.py for structured logging
• [ ] Implement request ID middleware in api/app.py to track requests end-to-end
• [ ] Add contextual logging to api/tasks/manager.py for task lifecycle events
• [ ] Add logging to each router module (api/routers/*.py) at entry/exit points
• [ ] Create docs/en/development/logging.md documenting log levels and debugging tips

• Add pytest-based integration tests for api/routers/video.py covering the happy path (theme → script → frames → video output) without hitting real APIs; mock the LLM, image generation, and TTS calls. This addresses the complete lack of visible test coverage and helps catch regressions in the core pipeline.
• Create API endpoint documentation (OpenAPI/Swagger schema cleanup or docs/api.md) detailing request/response schemas for each router (content, frame, video, tts, image); currently undocumented in the file list, making new contributor onboarding slow. Start with api/schemas/ and api/routers/ to reverse-engineer full spec.
• Implement graceful error handling and user-friendly error messages for common failure modes: missing config.yaml, unreachable ComfyUI endpoint, LLM API timeout, TTS service unavailable. Add a health check endpoint (api/routers/health.py exists but may be minimal) and example error responses in docs.

• High · Incomplete Dependency Pinning — requirements.txt. The requirements.txt file only specifies pyyaml>=6.0.0 without pinning exact versions or specifying upper bounds. This allows installation of any future version, including potentially vulnerable releases. Additionally, other critical dependencies (FastAPI, FFmpeg integration libraries, ML libraries) are not listed in the provided requirements.txt. Fix: Implement strict version pinning for all dependencies. Create a requirements.txt with specific versions (e.g., pyyaml==6.0.1) or use requirements-lock.txt with hash verification. Consider using tools like pip-tools or Poetry for dependency management.
• High · Missing Security Configuration in Docker — Dockerfile. The Dockerfile uses 'apt-get install' without specifying pinned package versions. Package managers may install vulnerable versions of curl, ffmpeg, and other system packages. Additionally, no explicit user privilege dropping is configured (running as root). Fix: Pin system package versions in apt-get install commands. Create a non-root user and switch to it before running the application. Example: 'RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app' and add 'USER appuser' before application execution.
• Medium · Plaintext Configuration File in Repository — config.example.yaml, docker-compose.yml. The config.example.yaml is present in the repository. While it's an example, it may contain sensitive configuration patterns or defaults that could be exploited. Additionally, docker-compose.yml shows config.yaml being created from example file without validation. Fix: Document all sensitive configuration options as environment variables instead of file-based config. Implement config validation to ensure sensitive values are not left as defaults. Add config.yaml to .gitignore and provide a template with clear security guidance.
• Medium · Potential Unvalidated File Upload/Processing Risk — api/routers/files.py, api/routers/video.py, api/routers/image.py. The file structure includes routers for files, images, video, and frame processing (api/routers/files.py, api/routers/video.py) but no visible input validation mechanisms in the provided structure. FFmpeg integration without proper input sanitization could lead to command injection vulnerabilities. Fix: Implement strict input validation for all file uploads and parameters. Use allowlists for file types and extensions. Sanitize all parameters passed to ffmpeg and external commands. Use subprocess with array arguments instead of shell=True to prevent command injection.
• Medium · Missing API Security Headers and Authentication — api/app.py, api/routers/health.py. The api/app.py structure suggests a FastAPI application, but no visible middleware or security decorators are shown for authentication, CORS, or rate limiting. The health check endpoint (api/routers/health.py) may be accessible without authentication. Fix: Implement authentication (JWT, OAuth2) for all API endpoints except those explicitly meant to be public. Add CORS middleware with restrictive origins. Implement rate limiting middleware. Add security headers (CSP, X-Content-Type-Options, etc.). Use FastAPI security utilities.
• Medium · Exposed External Service Integration — api/routers/llm.py, api/routers/tts.py. The presence of routers for llm.py and tts.py suggests integration with external services. Without visible API key management or secret rotation mechanisms, there's risk of credential exposure. Fix: Store all API keys and credentials in environment variables, never in configuration files or code. Use a secret management system (e.g., HashiCorp Vault, AWS Secrets Manager). Implement key rotation policies. Add credential validation at startup.
• Medium · Docker Compose Health Check Configuration Missing — docker-compose.yml. The docker-compose.yml does not show explicit health checks or resource limits (CPU, memory). This could lead to resource exhaustion attacks or undetected service failures. Fix: Add healthcheck configuration to docker-compose.yml services. Implement resource limits (memory, CPU). Configure logging drivers with appropriate retention policies. Add restart policies with limits to prevent restart loops.
• Low · China Mirror Support Complexity — undefined. The USE_CN_MIRROR build argument enables sed-based source modification which could be Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.