# AnimGen Public API workflow examples

Public API: beta, URL version `v1`, contract `1.3.0`. A verified AnimGen account and a server-side API key with `animations:read` and `animations:write` are required; generation needs sufficient credits and subscriptions raise limits. MCP is live in public beta at `https://api.animgen.com/mcp`; these are API examples, not MCP clients. Use the [MCP setup guide](https://animgen.com/docs/en/mcp/connect-clients) for OAuth.

中文说明：四种语言均默认只准备请求、报价，不启动付费生成。审核报价后才显式批准；恢复时保留原状态、账户、API Key 身份及幂等键。状态包含图片和提示词，不能提交到仓库；API Key 与签名下载地址不写入状态或日志。

Canonical source: Web `public/examples`. Doc `examples/public-api` is a mechanically synchronized copy (`animation-workflow.py` is named `python.py` there). Do not maintain separate implementations.

## Before running

- Download and inspect a script; never pipe downloaded code directly into a shell.
- Use a trusted local machine or server. Supply `ANIMGEN_API_KEY` privately using your secret manager. Do not put it in browser code, a game build, a repository, or an AI prompt.
- Read `GET /v1/models` and set `ANIMGEN_MODEL` to a currently supported first-frame model ID. Never assume a copied example model remains available.
- Set `IMAGE_PATH` to a private PNG for cURL, or PNG/JPEG/WebP for the other examples, at most 10 MiB. `ANIMGEN_PROMPT` is optional for TypeScript/C#/cURL.
- Use a private working directory outside version control. POSIX state/output files are private; on Windows restrict the directory ACL yourself. State includes the original image, prompt, request fingerprint, account/key identity, and idempotency key, but not the secret API key. Keep signed URLs private too.
- Each implementation uses its own state format. Do not swap languages/state files to retry an existing operation. Use one process per state and a new state only for an intentionally new operation.

## Choose one language

### Python 3.10+ (standard library)

The Web download is `animation-workflow.py`; in the Doc repository substitute `python.py` in both commands.

```bash
python3 animation-workflow.py prepare --image "$IMAGE_PATH" --model "$ANIMGEN_MODEL" \
  --prompt 'A character runs in place, side view, fixed camera.' --state hero-run.json
```

Review the quote. Set `APPROVED_CREDITS` to a nonnegative amount you explicitly accept, then:

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

### TypeScript (Node.js 22.14+)

```bash
node --experimental-strip-types typescript.ts
```

First leave `ANIMGEN_APPROVE_CREDITS` unset: it prepares, quotes, and stops. Review the quote, explicitly set that variable, then rerun the same command. Optional: `ANIMGEN_STATE` (default `animgen-state.json`), `ANIMGEN_OUTPUT`, `ANIMGEN_TIMEOUT_SECONDS`.

### C# (.NET 8 SDK)

Download both `csharp.cs` and `AnimGenPublicApiExample.csproj` into an isolated directory.

```bash
dotnet build AnimGenPublicApiExample.csproj
dotnet run --project AnimGenPublicApiExample.csproj
```

Approval and environment variables are the same as TypeScript. Leave `ANIMGEN_APPROVE_CREDITS` unset on the first run. This sample passed syntax parsing; the current documentation validation host does not have a .NET SDK, so no compilation or runtime pass is claimed. Compile and review before approving any real operation.

### cURL (Bash, curl 7.55+, jq, SHA-256 utility)

```bash
bash curl.sh
```

Approval works as above. Optional: `ANIMGEN_STATE_DIR` (default `animgen-curl-state`), `ANIMGEN_OUTPUT`, `ANIMGEN_TIMEOUT_SECONDS`. This example deliberately supports PNG input only. On macOS/Linux it uses `shasum` or `sha256sum` and standard POSIX tools.

## Spending, retries, and downloads

- API quotes do not lock prices. `ANIMGEN_APPROVE_CREDITS` / Python `--approve-credits` is only a local preflight check, **not a server-enforced cap**. API creation recalculates cost. Do not use these examples where an atomic maximum is required; use the live MCP's [spending safeguards](https://animgen.com/docs/en/mcp/spending-safeguards) through its separate OAuth tool workflow instead.
- Resume with the same saved state. The first create persists its request and idempotency key before submission. Ambiguous responses reuse them with the same account and credential identity. A different API key is a different idempotency scope even for the same account.
- Unresolved creates older than 24 hours stop for manual inspection. Local deadlines do not cancel remote work. Once a task ID is saved, rerunning only polls/downloads that task.
- Retries are bounded and honor `Retry-After`. Failed/cancelled tasks can still have useful outputs; they are saved before a nonzero exit. Handle nonzero exits as incomplete results, not proof that nothing was created or charged.
- Downloads use returned asset metadata and refresh expired links (401/403/404). Signed content requests and storage redirects carry **no API Authorization header**. Output files are streamed to private temporary files, checked for expected size, and published without overwriting different files.
- These are teaching examples, not general-purpose SDKs. Adapt durable state, monitoring, cancellation, and input validation to your environment. Mock validation does not guarantee a provider/model will accept a real request.

## Maintainer validation

From the Web repository:

```bash
npm run test:examples
npm run sync:examples -- --doc-root ../AIAnimGenDoc --check
```

Python and TypeScript use injected/offline mocks; cURL talks only to a temporary loopback mock server. No real credentials or paid jobs are used. TypeScript is also strictly type-checked. Optional C# syntax check: install `scripts/requirements-examples.txt` in an isolated environment, then run `npm run check:examples:csharp`; a .NET 8 build remains a separate stronger gate.