Authentication and image inputs

Authenticate from a trusted environment

Use Authorization: Bearer <API_KEY> on Public API requests. Keys are shown in plaintext only when created in Account → Developer. Keep them in a secret store, rotate by updating callers before revoking the old key, and avoid logging request headers.

A verified AnimGen account is required. Registered access starts with 1 concurrent job, a 3-job queue, 3 creates per minute, and 60 other requests per minute. Active subscriptions raise these account-wide limits. Read GET /account for the current tier, key scopes, and limits, and GET /credits/balance for available credits.

MCP uses OAuth and different, finer-grained scopes. Do not apply the API key scope table to MCP.

Option A: upload once, reuse a file ID

curl --fail-with-body https://api.animgen.com/v1/files \
  -H "Authorization: Bearer $ANIMGEN_API_KEY" \
  -F "[email protected]"

The response contains id, MIME type, dimensions, byte size, and SHA-256. Use the returned ID, not a Studio uploadId, filesystem path, or internal job identifier:

{
  "input": {
    "first_frame": {
      "type": "file",
      "file_id": "00000000-0000-4000-8000-000000000001"
    }
  }
}

The UUID above is a placeholder. Uploads accept PNG, JPEG, and WebP. The default multipart limit is 20 MB; the service also validates decoded images and dimensions. Handle the returned limit errors rather than trusting a filename or MIME declaration.

Option B: inline Base64

{
  "type": "base64",
  "media_type": "image/png",
  "data": "<PURE_BASE64_IMAGE_BYTES>"
}

Use pure Base64, without a data:image/...;base64, prefix. The decoded limit is 10 MB per image and 20 MB across inline images in a request. JSON/Base64 transport is larger than the raw file. Use a reusable upload for larger or repeatedly used images.

The Base64 content is persisted before a creation is accepted. Preserve the same bytes when retrying an idempotent request.

Option C: public HTTPS URL

{
  "type": "url",
  "url": "https://your-public-image-host.example/character.png"
}

Replace this illustrative hostname with a real, reachable image URL. The server must be able to fetch the image without your browser cookies. URLs must use public HTTPS on port 443 and cannot contain embedded credentials or fragments. Private, loopback, and link-local destinations are blocked; redirect targets are checked too.

Keep the bytes at that URL stable while quoting and creating. Do not use a private intranet address or a URL that returns a login page. Signed input URLs are sensitive and may expire.

Match the selected model

Every generation needs a first frame. A last frame or additional reference images is allowed only when the live model supports that mode; the request schema's overall maximum does not override a smaller model-specific maximum.

Use GET /models for valid modes and settings, and quote the full intended request before creation. For transparent sources, follow transparent animation. Then continue to the quickstart.