在开发内容平台、社交工具或自动化运营系统时,经常需要将视频片段转换为 GIF 动图。GIF 格式兼容性好,适合展示精彩瞬间、制作表情包或在无视频播放环境的页面中展示动态内容。
然而,视频转 GIF 是一个计算密集型任务,尤其是涉及分辨率调整和帧率控制时,无法在 HTTP 请求的瞬间完成。因此,我们需要一套基于异步任务的处理机制:先提交任务,稍后查询结果。
业务场景与需求
- 表情包制作工具:用户上传视频链接,设置
start(起始时间)和duration(时长),截取最精彩的 3 秒制作成 GIF。 - 内容预览:在网页列表中,将视频的某个片段转为 GIF 作为鼠标悬停时的动态预览,避免加载大视频文件。
- 核心需求:
- 异步处理:支持长耗时任务,先提交后查询。
- 参数灵活:支持自定义宽高、帧率(FPS)以及截取时间段。
- 结果获取:返回生成的 GIF 图片 URL 及文件大小信息。
实现思路
该接口采用标准的异步任务模式:
- Submit 阶段:传入视频 URL 和转换参数(如 fps=10, start=2, duration=3),获取
task_id。 - Query 阶段:轮询接口,传入
task_id,直到返回状态为成功并获取 GIF 链接。
代码实现
1. Python 自动化转换脚本(完整流程)
此脚本封装了提交和查询的完整逻辑。它会自动轮询任务状态,直到转换完成并下载 GIF。
import requests
import time
import os
def video_to_gif(video_url, output_filename="result.gif"):
base_url = "https://api.auth.top/api/v2g"
headers = {
"key": "9bf3ef53ef0060b5"}
# 第一步:提交任务
submit_params = {
"action": "submit",
"url": video_url,
"width": 480, # 设置宽度为 480px
"fps": 10, # 设置帧率为 10
"start": 2, # 从第 2 秒开始
"duration": 3 # 截取 3 秒时长
}
print("正在提交转换任务...")
resp = requests.get(base_url, headers=headers, params=submit_params)
result = resp.json()
if result.get("status") != "success":
print("任务提交失败:", result)
return
task_id = result.get("data", {
}).get("task_id") # 注意:根据实际结构获取 task_id
# 假设返回结构中 task_id 在 data 下,若无则直接在根节点,此处需按实际接口调整
# 这里假设返回示例中包含 task_id,若返回的 result 只有url则表示同步完成
# 根据描述 "action为submit时必传",通常是异步。
# 如果是异步模式,我们需要获取 task_id。这里模拟一个通用的异步轮询逻辑:
# 假设 submit 返回格式为: {"status": "success", "data": {"task_id": "xxx"}}
if 'data' in result and 'task_id' in result['data']:
task_id = result['data']['task_id']
print(f"任务已提交,ID: {task_id}。正在等待处理...")
# 第二步:轮询查询结果
while True:
time.sleep(2) # 每2秒查询一次
query_params = {
"action": "query",
"task_id": task_id
}
q_resp = requests.get(base_url, headers=headers, params=query_params)
q_result = q_resp.json()
# 判断状态,具体字段视接口而定,这里假设 status 字段
process_status = q_result.get("data", {
}).get("status")
if process_status == "finished" or q_result.get("result"):
print("转换完成!")
final_result = q_result.get("result", {
})
gif_url = final_result.get("url")
break
elif process_status == "failed":
print("转换失败")
return
else:
print(f"处理中... 当前状态: {process_status}")
else:
# 如果接口直接返回了结果(同步极速模式)
final_result = result.get("result", {
})
gif_url = final_result.get("url")
# 第三步:下载结果
if gif_url:
print(f"正在下载 GIF: {gif_url}")
img_data = requests.get(gif_url).content
with open(output_filename, 'wb') as f:
f.write(img_data)
print(f"保存成功: {output_filename}")
print(f"文件大小: {final_result.get('size')} 字节")
if __name__ == '__main__':
# 替换为实际的视频链接
video_link = "https://example.com/video.mp4"
video_to_gif(video_link)
2. Node.js 获取预览图(截取片段)
此示例展示了如何在前端或 Node.js 服务中,截取视频的第 5 秒开始,持续 2 秒的画面,生成 320px 宽的 GIF 预览图。
const axios = require('axios');
async function createPreviewGif(videoUrl) {
const apiUrl = 'https://api.auth.top/api/v2g';
const apiKey = '9bf3ef53ef0060b5';
try {
// 1. 提交转换任务
const submitResp = await axios.get(apiUrl, {
headers: {
'key': apiKey },
params: {
action: 'submit',
url: videoUrl,
width: 320, // 较小的宽度,适合网页预览
fps: 8, # 较低帧率,减小文件体积
start: 5, # 从第 5 秒开始
duration: 2 # 持续 2 秒
}
});
const taskId = submitResp.data.data?.task_id;
if (!taskId) {
console.log('无法获取任务ID');
return;
}
console.log(`任务ID: ${
taskId}, 等待处理...`);
// 2. 轮询查询结果
let resultUrl = null;
while (!resultUrl) {
await new Promise(resolve => setTimeout(resolve, 3000)); // 等待3秒
const queryResp = await axios.get(apiUrl, {
headers: {
'key': apiKey },
params: {
action: 'query',
task_id: taskId
}
});
const data = queryResp.data;
if (data.result && data.result.url) {
resultUrl = data.result.url;
console.log('转换成功!');
console.log('GIF 地址:', resultUrl);
console.log('尺寸:', data.result.width, 'x', data.result.height);
} else {
console.log('正在处理中...');
}
}
} catch (error) {
console.error('转换出错:', error.message);
}
}
// 使用示例
createPreviewGif('https://example.com/sample.mp4');
3. cURL 快速测试(同步/异步流程)
用于快速测试接口参数是否正确。
# 1. 提交任务
curl -X GET "https://api.auth.top/api/v2g?action=submit&url=https://example.com/video.mp4&width=480&fps=10&start=0&duration=3" \
-H "key: 9bf3ef53ef0060b5"
# 假设返回: {"status":"success", "data":{"task_id": "12345"}}
# 2. 查询任务 (替换 task_id)
curl -X GET "https://api.auth.top/api/v2g?action=query&task_id=12345" \
-H "key: 9bf3ef53ef0060b5"
# 3. 成功后返回示例
# {
# "status": "success",
# "message": "转换成功",
# "result": {
# "url": "https://v2.auth.top/v2g/upload/gif_xxx.gif",
# "size": 3886311,
# "width": 200,
# "height": 110
# }
# }
总结
我们可以灵活地将视频片段转换为 GIF。利用 start 和 duration 参数,可以精准控制截取范围,非常适合制作视频预览或提取高光时刻。在集成时,请务必注意采用异步轮询机制,避免因网络或处理延迟导致请求超时。