图生 GIF API

模型 ID：modelfold/image-to-gif

一次提交，轮询结果：优化提示词 → 可选保真抠图 → 1080p 视频 → GIF/WebP。标准用 bytedance/v1-pro-fast-image-to-video（5 秒），高级用 wan/2-7-image-to-video（5 秒）。动物透明 GIF 是独立工具。

参数

Parameter	Type / values	Default
image_url	HTTPS URL	required / 必填
prompt	string, 1–2000 characters	required / 必填
cutout	boolean	false
cutout_subject	auto	person
quality	standard	advanced
optimize_prompt	boolean	true
output	gif	webp
size	256	443
frames	0	integer 8–16
transparent	boolean	true when cutout=true; otherwise forced false

输入支持 JPEG/PNG/WebP，最大 10 MB、2000 万像素。输入及结果保留 24 小时。cutout=false 不调图片接口；optimize_prompt=false 不调对话接口，原样使用描述，仅抠图时追加必要背景约束。自动抠图用 Recraft；指定主体用编辑蒙版合成原图像素，仅对齐质量差时回退编辑结果。推荐全彩、柔和边缘的 WebP。自动选循环段，AI 动作及主体一致性可能有差异。

报价与计费

GET /api/tools/image-to-gif/quote?quality=standard&cutout=false&optimize_prompt=true

报价返回 credits（本次最多预扣的积分）。提交时一次预扣上限；成功后按实际用量结算并退还差额，不会超过预扣上限；任一步失败全额退款。提交的 expectedCredits 与当前报价不同时返回 409，需重新获取报价。

组合	最多预扣（提示词优化开/关）
Standard / 不抠图	44 / 44
Standard / auto	45 / 45
Advanced / 不抠图	145 / 144
Advanced / auto	146 / 146

定向抠图（person/animal/object）比 auto 略贵。以上为示例，实际以 /quote 返回为准。

一次提交示例

以下两个 input 均可用于下方 curl、Python、Node 示例，替换自己的公开图片 URL 和 API Key。无需二次确认。

1. 标准不抠图

curl https://modelfold.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-gif-example-1' \
  -d '{"model": "modelfold/image-to-gif", "input": {"image_url": "https://example.com/photo.png", "prompt": "The person waves hello naturally and returns to the initial pose.", "cutout": false, "quality": "standard", "optimize_prompt": false}}'

import os, uuid, requests
body = {'model': 'modelfold/image-to-gif', 'input': {'image_url': 'https://example.com/photo.png', 'prompt': 'The person waves hello naturally and returns to the initial pose.', 'cutout': False, 'quality': 'standard', 'optimize_prompt': False}}
r = requests.post("https://modelfold.ai/api/v1/jobs/createTask", json=body,
    headers={"Authorization": "Bearer " + os.environ["MODELFOLD_API_KEY"],
             "Idempotency-Key": str(uuid.uuid4())})
r.raise_for_status()
print(r.json()["data"]["taskId"])

const r = await fetch("https://modelfold.ai/api/v1/jobs/createTask", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.MODELFOLD_API_KEY}`,
    "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID()},
  body: JSON.stringify({"model": "modelfold/image-to-gif", "input": {"image_url": "https://example.com/photo.png", "prompt": "The person waves hello naturally and returns to the initial pose.", "cutout": false, "quality": "standard", "optimize_prompt": false}})
});
if (!r.ok) throw new Error(await r.text());
console.log((await r.json()).data.taskId);

2. 高级透明抠图

curl https://modelfold.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-gif-example-2' \
  -d '{"model": "modelfold/image-to-gif", "input": {"image_url": "https://example.com/product.png", "prompt": "The product rotates smoothly, returning to its starting angle.", "cutout": true, "cutout_subject": "auto", "quality": "advanced", "transparent": true, "optimize_prompt": true, "output": "both"}}'

import os, uuid, requests
body = {'model': 'modelfold/image-to-gif', 'input': {'image_url': 'https://example.com/product.png', 'prompt': 'The product rotates smoothly, returning to its starting angle.', 'cutout': True, 'cutout_subject': 'auto', 'quality': 'advanced', 'transparent': True, 'optimize_prompt': True, 'output': 'both'}}
r = requests.post("https://modelfold.ai/api/v1/jobs/createTask", json=body,
    headers={"Authorization": "Bearer " + os.environ["MODELFOLD_API_KEY"],
             "Idempotency-Key": str(uuid.uuid4())})
r.raise_for_status()
print(r.json()["data"]["taskId"])

const r = await fetch("https://modelfold.ai/api/v1/jobs/createTask", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.MODELFOLD_API_KEY}`,
    "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID()},
  body: JSON.stringify({"model": "modelfold/image-to-gif", "input": {"image_url": "https://example.com/product.png", "prompt": "The product rotates smoothly, returning to its starting angle.", "cutout": true, "cutout_subject": "auto", "quality": "advanced", "transparent": true, "optimize_prompt": true, "output": "both"}})
});
if (!r.ok) throw new Error(await r.text());
console.log((await r.json()).data.taskId);

轮询与上传

curl "https://modelfold.ai/api/v1/jobs/recordInfo?taskId=TASK_ID" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY"

每隔 3–5 秒轮询，直到 success 或 fail。progress.stage：optimizing / isolating / animating / rendering / done。resultJson 为 JSON 字符串，含 resultUrls 和 resultObject（gif、webp、optimizedPrompt、videoModel、expiresAt、size、frames、loop）。仅当 usage.settled=true 时，usage.credits 为最终实扣。

POST /api/tools/image-to-gif/generate: 可直接提交 input JSON，或以原始图片字节作为请求体、参数放 query。需 Bearer API Key 与 Idempotency-Key（1–150 字符）。返回相同任务协议，轮询 /api/tools/image-to-gif/tasks/:id。

错误与退款

HTTP	Meaning
400	Invalid parameters / image
401	Authentication required
402	Insufficient credits / Key limit
403	Account restricted
404	Task not owned / file expired
409	Price changed / idempotency conflict
413	Image exceeds 10 MB
429	Rate limit / pending tasks
500	Internal request error

提交 HTTP 成功不代表生成成功。请检查 state、failMsg；任务失败最终扣费为 0，整单预扣全退（包括前面已成功的阶段）。相同幂等键与相同参数会返回原任务。