动物 GIF API

一次提交，自动跑完，只需轮询结果。默认透明背景；关闭后保留原图背景，不调用任何图片模型。

接口与参数

POST /api/tools/animal-gif/prepare

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

可提交 JSON（用 image_url），或直接以图片二进制作为请求体上传（Content-Type: application/octet-stream），其他参数放查询字符串；无需单独上传或确认。

Parameter	Type / default	说明
image_url / image upload	string / binary, required	JSON 使用公开 HTTPS 图片地址，上传使用原始 JPEG/PNG/WebP 请求体；最大 10 MB / 2000 万像素，无 JSON image 字段。
prompt	string, required	1–2000 字动作描述；不透明时直接作为视频提示词。
subject	string, animal	可选抠图主体，最多 200 字；不透明时不用于生成。
transparent	boolean, true	true：抠图→生成动作→透明处理；false：原图生成动作→处理不透明 GIF/WebP。查询参数仅接受 true/false。
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	报价积分；不一致返回 409，不扣费。

两档价格

价格 = 上游真实成本 × 后台运行时加价配置，向上取整。透明：图片 3 + 视频 16 积分；不透明：仅视频 16 积分。加价配置为 1.2 时分别为 23 与 20 积分，实际以实时报价为准。实扣等于提交时预计价格；任一步失败（含上游成本变化）全额退款。

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

透明背景示例

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)

保留原背景示例

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)

轮询与下载

{"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"

每 5 秒轮询，直到 state 为 success 或 fail。解析 resultJson 后读取 resultObject.gif / webp、transparent、size、frames、expiresAt。usage.credits 是实扣；失败时 usage.settled=true 且 credits=0 表示全额退款。progress.transparent 标识模式；透明阶段为 isolating→animating→rendering，不透明为 animating→rendering，完成为 done。文件保留 24 小时。不透明方形输出居中裁切视频；模型生成可能改变外观或背景。

无效参数 400；鉴权 401/403；余额不足 402；任务不存在 404；报价或幂等冲突 409；上传超限 413；限流 429。已受理的失败任务可返回 HTTP 200，须检查 state=fail。

旧版兼容

原 createTask 协议（model=modelfold/animal-gif，参数放 input）及可选 confirm_cutout 保留兼容；transparent=false 忽略 confirm_cutout，新接入使用上述一步提交接口。