视频转 GIF API

上传视频或提供公开视频 URL，转换为 GIF。与在线工具共用积分钱包和调用结果记录。

默认 1 秒 1 积分，管理员可在「配置 → 视频转 GIF：每秒积分」修改。费用 = 向上取整的片段秒数 × gifPricing.perSecond，无基础费。通过 GET /api/config 获取实时价格。默认单价下，5 秒片段收费 5 积分，转换失败或任务中断自动退款。

支持 MP4、WebM、MOV，最大 50 MB。片段最长 30 秒，输出保持比例并限制在 720 × 720 内，不放大原视频。全站同时处理 2 个转换，处理超时 90 秒。结果保存在调用记录中，请及时下载（沿用结果文件 30 天保留规则）。

接口

POST /v1/tools/video-to-gif

Authorization: Bearer YOUR_MODELFOLD_API_KEY

本工具直接提交转换参数，不使用模型 ID。

请求参数

Content-Type: application/json

请求示例

{
  "url": "https://example.com/video.mp4",
  "start": 0,
  "duration": 5,
  "width": 480,
  "fps": 15,
  "loop": true,
  "expectedCredits": 5
}

参数表

参数	类型	默认值	限制
url	string	—	公开 HTTP(S) 视频地址
start	number	0	≥ 0 秒
duration	number	5	> 0、≤ 30 秒，且不超过原视频时长
width	number / string	480	320, 480, 640, "original" (≤ 720)
fps	number	15	10, 15, 20
loop	boolean	true	true = 无限循环；false = 播放一次
expectedCredits	number	可选	报价变化时返回 HTTP 409

上传文件时使用 Content-Type: application/octet-stream 发送视频原始字节，其余参数放在 URL 查询字符串里，不传 url。

curl -X POST 'https://modelfold.ai/v1/tools/video-to-gif?start=0&duration=5&width=480&fps=15&loop=true&expectedCredits=5'   -H "Authorization: Bearer $MODELFOLD_API_KEY"   -H 'Content-Type: application/octet-stream'   --data-binary @video.mp4

返回示例

HTTP 202:

{"ok":true,"id":"123","credits":5}

轮询及下载

GET /v1/tools/video-to-gif/jobs/:id

curl https://modelfold.ai/v1/tools/video-to-gif/jobs/123 \
  -H "Authorization: Bearer $MODELFOLD_API_KEY"

使用同一 API Key，每 2 秒查询一次。状态为 pending、ok 或 failed，仅任务所属用户可查。失败退款后 credits=0。网络断开时先查询任务或调用记录，避免重复提交扣费。

{"ok":true,"id":"123","status":"ok","credits":5,"url":"/uploads/outputs/example.gif","size":123456,"latencyMs":2500}

url 为相对于 https://modelfold.ai 的路径，size 单位为字节，latencyMs 单位为毫秒。生成结果也会出现在账户调用记录中。

错误码

HTTP	错误码	说明
400	invalid_parameters / invalid_video	参数无效、视频格式不支持或片段超出时长
401	unauthorized / invalid_api_key	使用有效 API Key
402	insufficient_credits / key_credit_limit_exceeded	充值或提高 Key 额度
409	price_changed	核对返回的 credits 和 perSecond 后重新提交
413	file_too_large	最大 50 MB
429	busy	同时已有两个转换任务，请稍后重试
504	timeout	输入处理超时

返回 HTTP 202 后发生的转换错误，通过任务状态 failed 报告，并自动退款。