Animal GIF API

Submit once, then poll for the GIF/WebP. Transparent backgrounds are enabled by default; disable them to keep the original background without calling an image model.

Endpoint and parameters

POST /api/tools/animal-gif/prepare

Authorization: Bearer <API_KEY> · Idempotency-Key: 1–150 characters; reuse the same key and parameters on network retries.

Send JSON with image_url, or upload the image bytes as the request body (Content-Type: application/octet-stream) and put all other parameters in the query string. No separate upload or confirmation is needed.

Parameter	Type / default	Description
image_url / image upload	string / binary, required	Public HTTPS URL in JSON, or raw JPEG/PNG/WebP body; ≤10 MB, ≤20 MP. No JSON image field.
prompt	string, required	1–2000 characters; action description, sent directly to video generation in opaque mode.
subject	string, animal	Optional isolation subject, ≤200 characters; unused in opaque mode.
transparent	boolean, true	true: isolate → animate → remove background; false: animate original → render opaque GIF/WebP. Query accepts true/false only.
size	integer, 443	256 / 443 / 512; square output
frames	integer, 0	0: automatic 8–16; or integer 8–16
output	string, both	gif / webp / both
expectedCredits	number, optional	Quoted credits; mismatch returns 409 without a charge.

Pricing

Price = actual upstream cost × runtime admin markup, rounded up. Transparent: image (3 credits) + video (16 credits); opaque: video only (16 credits). With markup 1.2 these are 23 and 20 credits. Always fetch a current quote; the final debit equals the accepted estimate. Any failure is fully refunded, including an upstream cost change.

curl 'https://modelfold.ai/api/tools/animal-gif/quote?transparent=true'
curl 'https://modelfold.ai/api/tools/animal-gif/quote?transparent=false'

Transparent

curl

curl 'https://modelfold.ai/api/tools/animal-gif/prepare?prompt=walks%20naturally&subject=cat&transparent=true&size=256&frames=8&output=both' \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Idempotency-Key: animal-true-$(uuidgen)" \
  -H 'Content-Type: application/octet-stream' --data-binary @animal.jpg

Python

import os, uuid, requests
with open("animal.jpg", "rb") as image:
    response = requests.post(
        "https://modelfold.ai/api/tools/animal-gif/prepare",
        headers={"Authorization": "Bearer " + os.environ["MODELFOLD_API_KEY"],
                 "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/octet-stream"},
        params={"prompt": "walks naturally", "subject": "cat", "transparent": "true",
                "size": 256, "frames": 8, "output": "both"}, data=image, timeout=180)
response.raise_for_status()
print(response.json()["data"]["taskId"])

Node.js 18+

import { readFile } from 'node:fs/promises'
import { randomUUID } from 'node:crypto'
const params = new URLSearchParams({ prompt: 'walks naturally', subject: 'cat',
  transparent: 'true', size: '256', frames: '8', output: 'both' })
const response = await fetch('https://modelfold.ai/api/tools/animal-gif/prepare?' + params, {
  method: 'POST', headers: { Authorization: `Bearer ${process.env.MODELFOLD_API_KEY}`,
    'Idempotency-Key': randomUUID(), 'Content-Type': 'application/octet-stream' },
  body: await readFile('animal.jpg')
})
const json = await response.json()
if (!response.ok) throw new Error(json.msg)
console.log(json.data.taskId)

Original background

curl

curl 'https://modelfold.ai/api/tools/animal-gif/prepare?prompt=walks%20naturally&subject=cat&transparent=false&size=256&frames=8&output=both' \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Idempotency-Key: animal-false-$(uuidgen)" \
  -H 'Content-Type: application/octet-stream' --data-binary @animal.jpg

Python

import os, uuid, requests
with open("animal.jpg", "rb") as image:
    response = requests.post(
        "https://modelfold.ai/api/tools/animal-gif/prepare",
        headers={"Authorization": "Bearer " + os.environ["MODELFOLD_API_KEY"],
                 "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/octet-stream"},
        params={"prompt": "walks naturally", "subject": "cat", "transparent": "false",
                "size": 256, "frames": 8, "output": "both"}, data=image, timeout=180)
response.raise_for_status()
print(response.json()["data"]["taskId"])

Node.js 18+

import { readFile } from 'node:fs/promises'
import { randomUUID } from 'node:crypto'
const params = new URLSearchParams({ prompt: 'walks naturally', subject: 'cat',
  transparent: 'false', size: '256', frames: '8', output: 'both' })
const response = await fetch('https://modelfold.ai/api/tools/animal-gif/prepare?' + params, {
  method: 'POST', headers: { Authorization: `Bearer ${process.env.MODELFOLD_API_KEY}`,
    'Idempotency-Key': randomUUID(), 'Content-Type': 'application/octet-stream' },
  body: await readFile('animal.jpg')
})
const json = await response.json()
if (!response.ok) throw new Error(json.msg)
console.log(json.data.taskId)

Poll and download

{"code":200,"data":{"taskId":"UUID","state":"queued","credits":23}}

curl 'https://modelfold.ai/api/tools/animal-gif/tasks/UUID' \
  -H "Authorization: Bearer $MODELFOLD_API_KEY"

Poll every 5 seconds until state is success or fail. Parse resultJson to read resultObject.gif / webp, transparent, size, frames and expiresAt. usage.credits is the final charge; usage.settled=true with credits=0 means full refund on failure. progress.transparent identifies the mode. Transparent stages: isolating → animating → rendering; opaque: animating → rendering; done when complete. Files expire after 24 hours. Opaque square output center-crops the video; generation may change appearance or background.

Invalid requests return 400; authentication 401/403; insufficient credits 402; missing task 404; price/idempotency conflict 409; oversized upload 413; rate limit 429. Accepted failed tasks return state=fail even with HTTP 200.

Legacy compatibility

The existing createTask protocol (model=modelfold/animal-gif, parameters in input) and optional confirm_cutout remain compatible; transparent=false ignores confirm_cutout. New integrations use the single-submit endpoint above.