xhongc/ai_story: a self-hosted pipeline that turns a story prompt into a shot-by-shot video

What xhongc/ai_story actually automates

Most AI video tools stop at one step. You write a prompt, you get a clip, and you stitch the rest together yourself. AI Story takes the opposite position: the input is a story theme or an outline, and the system is expected to carry it through script rewriting, scene splitting, image generation, camera-move planning and finally image-to-video, with a progress view for each stage. The README describes the chain as one continuous flow and says every stage can be paused, resumed, retried or rolled back.

The audience is narrow and fairly specific. This is not a browser toy for someone who wants a free story generator in thirty seconds. It is a Django application with a Celery worker, a Redis broker and a MySQL connection, which means the person deploying it is expected to own a server. The README lists short-video production, knowledge explainers, children's stories and video prototypes as the intended uses, and the screenshots show a Chinese-language interface. If you want a hosted generator, this is the wrong shape of tool.

The pipeline chain and the Celery worker behind it

The architecture visible in the repository is a Django backend plus a Celery worker plus Redis, with a Vue front end served separately. The README calls the internal design a Pipeline chain-of-responsibility pattern, which matters for one practical reason: stages are meant to be independently re-runnable. If image generation produces a bad frame, the workflow does not have to start over from the script.

Redis does double duty as cache and message queue in the compose file. The backend runs under gunicorn with the gevent worker class, and Celery is started from the backend directory. The README warns about exactly this: if Celery is not launched from /app/backend, it fails with "Unable to load celery application. The module config was not found." That is a real deployment trap, not a hypothetical one, and it is the kind of error a first-time user will hit within minutes.

Model selection is a configuration concern rather than a code concern. The README states that each stage can be pointed at multiple models, with load balancing across polling, random, weighting and least-load strategies, plus rate limiting and usage statistics. That design assumes you have more than one API key to spread across, which is a reasonable assumption for a production setup and an unnecessary complication for a single-user install.

Installing with Docker Compose and creating the first admin

The README gives a Compose file that pulls prebuilt images rather than building from source, which is the fastest path. Create a compose file with the redis, backend, celery and frontend services, then start it. The frontend is published on port 3000.

services:
  redis:
    image: redis:7-alpine
    restart: unless-stopped
  backend:
    image: xhongc/ai_story-backend
    restart: unless-stopped
    volumes:
      - ./data/backend:/app/backend/data
      - ./storage:/app/storage
    environment:
      - DJANGO_SETTINGS_MODULE=config.settings.production
      - REDIS_HOST=redis
    depends_on:
      - redis

The Celery service uses the same image but overrides the working directory, which is the detail the README flags as the cause of the module-not-found error.

  celery:
    image: xhongc/ai_story-backend
    working_dir: /app/backend
    command: celery -A config worker -l info -P gevent
    environment:
      - DJANGO_SETTINGS_MODULE=config.settings.production
      - REDIS_HOST=redis
    depends_on:
      - redis

Start everything, then create the administrator account. The README gives both the hyphenated and the space-separated form of the command.

docker compose up -d
docker compose exec backend python backend/manage.py createsuperuser

After that, http://localhost:3000 serves the application. The README does not document what the first screen asks for, so expect to configure model providers before a run will complete. For a source build, the repository also carries a docker-compose.yml that builds from docker/Dockerfile and expects MYSQL_DB_NAME, MYSQL_USER, MYSQL_PASSWORD, MYSQL_HOST and MYSQL_PORT in the environment.

Where the design bites: external APIs, MySQL and an unfinished mode

The single largest constraint is that this is an orchestrator, not a generator. The README lists Stable Diffusion, DALL-E and Midjourney for images and Runway and Pika for video, all as external services. Nothing in the repository generates pixels locally. Your output quality, your cost per video and your throughput are therefore decided by whichever providers you plug in, and a slow or rate-limited video API will stall the whole chain no matter how well the Celery worker is tuned.

The database layer is the second constraint. The pyproject file pins mysqlclient and the compose file passes MySQL connection variables, while .env.example shows a sqlite:///db.sqlite3 DATABASE_URL for development. Those two paths are not equivalent, and the README does not describe a supported migration between them. Anyone who prototypes on SQLite and then deploys against MySQL is on their own.

Third, director mode. The README shows screenshots of it and states it is still under development, with finer storyboard and video control promised. Treat those screenshots as a preview of intent, not as shipped functionality. The same caution applies to the release history: no releases were retrieved for this repository, so the container image tags are the practical versioning surface. The README does not document rollback of an image tag.

How it differs from a hosted AI story generator

The obvious comparison is a hosted generator such as Perchance's story tools or a browser-based AI story maker. Those require no server, no keys and no database, and they are free to try. The difference is not quality, it is control. A hosted generator decides which model runs, how long your text is retained and what the per-run limits are. AI Story moves all of that into your infrastructure: you supply the keys, you decide the model per stage, and the intermediate artifacts (scripts, storyboards, prompts, generated images) live in your own storage volume.

That trade is only worth making if you need it. A writer experimenting with story ideas gains nothing from running Redis and MySQL. A studio that needs consistent character prompts across dozens of episodes, or that cannot send scripts to a third-party service it does not control, gains a great deal. The load-balancing and rate-limit configuration in the README only makes sense in the second scenario.

Licence and the cost of keeping it running

The project uses CC BY-NC-SA 4.0. The README states that personal study and non-commercial use are permitted, modification and derivative works are permitted under the same licence, and commercial use is prohibited without a separate authorisation, with a contact address given for that. This is not an open source software licence in the usual sense, and it is the first thing to check against your intended use. Nothing here is legal advice; if revenue depends on the output, get your own reading of the terms.

Upgrade cost is mostly operational. The pinned stack is Django 3.2.15 with djangorestframework 3.14.0 and celery 5.5.0b2, a beta release. Django 3.2 is an old line, so security patches for the framework itself will not arrive indefinitely, and moving to a newer Django means auditing the DRF and Celery pins together. The compose file mounts ./backend into the Celery container for source builds, which makes local edits take effect without a rebuild but also means the running code and the image can drift apart. Budget for the API spend separately: image and video generation are billed per call by the providers you configure, and the README's usage and cost statistics exist precisely because that bill is the dominant running cost.

Editorial conclusion

Adopt xhongc/ai_story if you want the whole script-to-video chain inside your own infrastructure and you already hold API keys for the language, image and video providers it calls, or you are comfortable wiring them in through the model configuration screen. Do not adopt it for commercial production: the licence is CC BY-NC-SA 4.0 and the README states commercial use requires a separate authorisation, and do not expect an offline generator, because images and clips come from external paid APIs. Verify three things before you commit time: that the image and video providers you intend to use are reachable from your network, that your MySQL and Redis instances are sized for the Celery worker that runs with -P gevent, and whether the director mode you see in the screenshots is finished, since the README labels it as still in development.

Frequently asked questions

Official sources

1. Issues
2. README
3. xhongc/ai_story on GitHub