Add bulk-csv-videos example

README.md

@@ -6,6 +6,7 @@ Clone this repository, or open the directory of the example you want. Each examp
 
 ## Examples
 
+- [bulk-csv-videos](examples/bulk-csv-videos) renders one video per row of a CSV from a single template with merge fields, tracked in a resumable manifest, with an optional AI step where Claude writes each row's headline and image prompt. Companion code for [Generate videos in bulk with an API and an AI agent](https://shotstack.io/learn/bulk-create-videos-from-csv-and-ai/).
 - [instagram-ai-video](examples/instagram-ai-video) generates a script, voiceover and background image with AI, renders a 1080x1920 video, and publishes it as an Instagram Reel. Companion code for [How to automate Instagram posts with AI video](https://shotstack.io/learn/automate-instagram-posts-with-ai-video/).
 - [rapidreels](examples/rapidreels) creates faceless short-form videos using generative AI. [View demo](https://shotstack.io/demos/social-media-video-maker/).
 - [reelestate](examples/reelestate) turns static real estate images into fully edited video slideshows. [View demo](https://shotstack.io/demos/real-estate-video-listing-maker/).

examples/bulk-csv-videos/.env.example

@@ -0,0 +1,4 @@
+SHOTSTACK_API_KEY=your_sandbox_api_key
+SHOTSTACK_ENV=stage
+SHOTSTACK_TEMPLATE_ID=your_stage_template_id
+ANTHROPIC_API_KEY=your_anthropic_api_key

examples/bulk-csv-videos/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.env
+products*.csv
+batch-results*.json

examples/bulk-csv-videos/README.md

@@ -0,0 +1,100 @@
+# Bulk videos from a CSV
+
+Render one video per row of a CSV from a single reusable template: create the template with merge
+fields, generate and validate a 100-row dataset, submit one template render per row at a safe pace,
+and track every render in a resumable manifest. The submit loop is implemented twice, in Node.js and
+in Python. An optional AI step has Claude write each row's headline and text-to-image prompt, which
+the same pipeline validates like any other input.
+
+Companion code for [Generate videos in bulk with an API and an AI agent](https://shotstack.io/learn/bulk-create-videos-from-csv-and-ai/).
+
+## Requirements
+
+- A [Shotstack account](https://dashboard.shotstack.io/register) with your **sandbox** API key
+  (dashboard menu under your account name, top right, under **API Keys**)
+- Node.js 20 or later, or Python 3 for the submit loop
+- Optional, for the AI step: an [Anthropic API key](https://platform.claude.com/)
+
+Sandbox renders are watermarked, and your account needs at least one credit to use the environment.
+
+## Setup
+
+```bash
+git clone https://github.com/shotstack/shotstack-cookbook.git
+cd shotstack-cookbook/examples/bulk-csv-videos
+npm install
+```
+
+Set your sandbox key and environment:
+
+```bash
+export SHOTSTACK_API_KEY="your_sandbox_api_key"
+export SHOTSTACK_ENV="stage"
+```
+
+## Run
+
+1. Create the template and keep the returned template id:
+
+```bash
+curl --fail-with-body \
+  --request POST \
+  "https://api.shotstack.io/edit/stage/templates" \
+  --header "Accept: application/json" \
+  --header "Content-Type: application/json" \
+  --header "x-api-key: ${SHOTSTACK_API_KEY}" \
+  --data-binary @template.json
+```
+
+2. Generate the 100-row dataset:
+
+```bash
+node generate-data.mjs
+```
+
+3. Preflight three rows, then submit and poll (Node or Python):
+
+```bash
+export SHOTSTACK_TEMPLATE_ID="your_stage_template_id"
+SHOTSTACK_ROW_LIMIT=3 node bulk-render.mjs submit
+node bulk-render.mjs status
+```
+
+```bash
+SHOTSTACK_ROW_LIMIT=3 python3 bulk_render.py submit
+python3 bulk_render.py status
+```
+
+Remove `SHOTSTACK_ROW_LIMIT` for the full batch. `node bulk-render.mjs summary` (or the Python
+equivalent) reads the local manifest without calling any API.
+
+4. Optional AI step — Claude writes each row's headline and image prompt, the script validates them,
+   and the render loop runs unchanged on the new file. Use a separate manifest, because the AI-written
+   rows differ from rows already tracked in `batch-results.json`:
+
+```bash
+export ANTHROPIC_API_KEY="your_anthropic_api_key"
+node generate-data-ai.mjs
+CSV_PATH=products-ai.csv MANIFEST_PATH=batch-results-ai.json node bulk-render.mjs submit
+```
+
+If your template has a `text-to-image` asset with an `{{IMAGE_PROMPT}}` placeholder, the AI-written
+prompt drives it. Templates without the placeholder ignore the extra field.
+
+## What happens
+
+`submit` validates the CSV, queues one template render per row, and records every render in the
+manifest. `status` polls each render until it is `done` or `failed` and retrieves the hosted video
+URL for finished renders. Each command ends with a status table and the count of hosted videos. The
+first three rows finish in under a minute; the full batch takes several minutes at the default
+one-request-per-second pace.
+
+## Notes
+
+- Templates belong to the environment they were created in. Re-create the template with your
+  production key and `SHOTSTACK_ENV=v1` before a production run; the ids will differ.
+- The manifest (`batch-results.json`) makes reruns safe: rows with a render id are skipped, and
+  only confirmed failures are retried with `SHOTSTACK_RETRY_FAILED=true`.
+- A row marked `unknown` means the process stopped before the API confirmed the request. Check the
+  render dashboard first. To retry the row, delete its entry from the manifest and run `submit` again.
+- Do not run the Node and Python submitters against the same manifest at the same time.