Alpha Educational Video API skill for Andy

SKILL.md

name	andy-educational-video-api
description	Generate short educational videos from simple teaching prompts through the Alpha educational video API.

Educational Video API

Use this service to generate a short educational MP4 from a simple teaching idea.

Configuration

Set these values before using the API:

ALPHA_VIDEO_API_URL=https://andy-video-api-production.up.railway.app
ALPHA_VIDEO_API_KEY=<provided separately>

Treat the API key as a secret. Send it only in the Authorization header. Do not place it in URLs, documents, or chat messages.

Each API key has its own private video history. Listing, status checks, cancellation, and downloads work only for videos created with the same key. The service response includes created_by so the credential identity can be confirmed without exposing the key.

Prompting

Prefer a short, atomic teaching request:

how atoms work, grade 6

why the moon causes tides, grade 7

how a negative supply shock causes stagflation, AP macroeconomics

Do not prescribe a script, runtime, scene list, visual treatment, or production workflow unless the user explicitly needs a correction. The service expands the request internally and chooses the teaching scope, pacing, visuals, and timing using its learning-science pipeline.

Videos longer than 3 minutes are not recommended yet. If the user asks for a broad topic, start with one focused concept rather than requesting a long survey video.

Generation Time

A finished video can take over an hour to generate. This is normal: the service puts substantial work into the teaching structure, visuals, narration, animation, rendering, and final MP4. Do not treat a long preparing, queued, or generating period as a failure by itself. Keep polling until the API returns succeeded, failed, or canceled.

Create A Video

Generate a unique idempotency key and request ID for each intended video. Reuse both values when retrying the same submission so a network retry does not create a duplicate render and operators can trace the request without exposing your bearer token.

curl -sS -X POST "$ALPHA_VIDEO_API_URL/v1/videos" \
  -H "Authorization: Bearer $ALPHA_VIDEO_API_KEY" \
  -H "Idempotency-Key: <unique-client-generated-key>" \
  -H "X-Request-Id: <unique-client-generated-request-id>" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"how atoms work, grade 6"}'

The service returns a video id, a status_url, and a cancel_url. The first status is normally preparing while the service improves the short prompt internally.

Poll Until Finished

curl -sS \
  -H "Authorization: Bearer $ALPHA_VIDEO_API_KEY" \
  "$ALPHA_VIDEO_API_URL/v1/videos/<video_id>"

Poll about every 20 seconds, including during long generation runs that take over an hour. Status values:

preparing
queued
generating
succeeded
failed
canceled

When the status is succeeded, the response contains result.download_url.

Download The MP4

curl -sS -L \
  -H "Authorization: Bearer $ALPHA_VIDEO_API_KEY" \
  "$ALPHA_VIDEO_API_URL/v1/videos/<video_id>/download" \
  -o educational-video.mp4

Generated files are retained for 30 days. Download important MP4s promptly and tell the user when a file is approaching its artifacts_expires_at date. Lightweight run metadata remains available after artifacts expire.

Cancel A Video

Cancel a request when the user no longer wants it:

curl -sS -X POST \
  -H "Authorization: Bearer $ALPHA_VIDEO_API_KEY" \
  "$ALPHA_VIDEO_API_URL/v1/videos/<video_id>/cancel"

Cancellation works while the service is improving the prompt, waiting for a worker, or generating the video.

List Recent Videos

curl -sS \
  -H "Authorization: Bearer $ALPHA_VIDEO_API_KEY" \
  "$ALPHA_VIDEO_API_URL/v1/videos?limit=20"

Optional status filter:

?status=preparing
?status=queued
?status=generating
?status=succeeded
?status=failed
?status=canceled

If creation returns HTTP 429, the queue is full. Wait for the Retry-After duration before retrying with the same idempotency key.