API quickstart: image to downloaded assets

Prerequisites

The Public API is in public beta. You need a verified AnimGen account, an API key with animations:read and animations:write, and a trusted server or local machine. Generation requires sufficient account credits; subscriptions raise developer limits but are not an access requirement.

Create a key in Account → Developer. Supply it as the ANIMGEN_API_KEY environment variable through your secret manager or a private shell session. Never put it in browser JavaScript, a shipped game, a repository, or an AI conversation.

The base URL is https://api.animgen.com/v1. The URL compatibility version is v1; the documented schema version is 1.3.0.

1. Discover a supported model

curl --fail-with-body https://api.animgen.com/v1/models \
  -H "Authorization: Bearer $ANIMGEN_API_KEY"

Choose an id from data that supports your input mode. Inspect its durations, resolutions, ratios, and capability flags. Do not copy a model name from an old article.

For the first-frame example below, use a model with supports_first_frame: true and first-frame support in modes. The example uses its published default options.

2. Prepare and quote without generating

Download and inspect the Python workflow example. It uses Python 3.10+ and only the standard library.

curl --fail-with-body -o animation-workflow.py \
  https://animgen.com/examples/animation-workflow.py

python3 animation-workflow.py prepare \
  --image character.png \
  --model 'PROVIDER:MODEL_FROM_CATALOG' \
  --prompt 'A character runs in place, side view, fixed camera.' \
  --state hero-run.json

Replace the image path and model ID. Preparation checks the catalog, creates an inline Base64 request, fetches a quote and balance, and saves a private state file. It does not call the paid creation endpoint.

The state file contains the input image and prompt. Keep it outside version control, restrict access, and remove it when no longer needed. It does not contain your API key.

3. Explicitly approve creation

Review the quoted credits and set APPROVED_CREDITS to the amount you accept. Then run:

python3 animation-workflow.py run \
  --state hero-run.json \
  --approve-credits "$APPROVED_CREDITS" \
  --output ./hero-output

The script re-quotes before the first create, rejects a quote above your local approval, persists an idempotency key, and submits the unchanged request once logically. It then polls and downloads available outputs.

4. Resume safely and inspect the result

If the command times out, rerun it with the same state file. If it saved a task ID, it resumes polling instead of creating. After an uncertain create response, it reuses the original key and payload within its conservative retry window.

Do not delete the state file and start again to “retry.” That creates a new logical operation and can spend twice. The sample refuses an unresolved create retry after 24 hours; inspect your task list or contact support before proceeding.

At any terminal state, the script saves all available assets before reporting failure or cancellation. It exits nonzero for an incomplete result and never treats a partial export as full success. Saved filenames use asset IDs, not names supplied by a remote server.

What the request does

The example requests a regular, full-length animation with PNG frames ZIP, 24 frames, and 512 × 512 output. These are example export choices, not the API defaults or a universal quality recommendation.

To use reusable uploads or a public URL, read authentication and image inputs. For lifecycle handling, read polling and downloads and errors and retries. The exact contract is available in OpenAPI JSON.

The Python example is tested against a local mock, not by spending credits on a production generation. Use a small, explicitly approved task for your own integration check. Other languages and their validation scope are listed in runnable examples; exact parameters are generated in the API reference.