aifroi 开放平台 API 文档

基础 URL:https://aifroi.com/api/v1。通过开放平台 API 可程序化调用 aifroi 的 AI 视频生成服务。

概述

通过开放平台 API 可程序化调用 aifroi 的 AI 视频生成服务。所有接口以 https://aifroi.com/api/v1 为基础 URL,采用 RESTful 风格,请求/响应体为 JSON。

认证方式

所有接口需鉴权。方式一(直传):请求头带 X-API-Key + X-API-Secret;方式二(签名):X-API-Key + X-Timestamp + X-Signature(HMAC-SHA256, 时间窗 ±5 分钟)。API Key/Secret 在账户关联页获取,请妥善保管。

账户接口

查询账户算力余额、套餐权益与调用配额,用于生成前的额度预检。

视频任务

创建视频生成任务、查询任务状态与产出。任务进入终态后可通过查询接口或 Webhook 回调获取成片 URL(永久公链)、封面与时长。

模板管理

查询与使用视频模板,按模板批量化生成。

Webhook 回调

任务终态(完成/失败)时向配置的 callbackUrl 主动推送事件,签名 X-Webhook-Signature = HMAC-SHA256(apiSecret, body)。回调是推的优化,查询接口是拉的兜底,二者对同一任务幂等。

错误码

统一错误响应体含 errorCode 与 error 文案。常见:401 鉴权失败、403 权限/配额不足、429 超日调用上限、422 参数校验失败。

SDK & 示例

提供请求签名与调用示例,便于快速接入。

开放平台 API

v1.0

概述

欢迎使用开放平台 API。通过本 API,您可以程序化地调用视频生成服务, 实现视频任务的创建、查询和管理。

Base URL

https://aifroi.com/api/v1

协议规范

  • • 请求格式:JSON
  • • 响应格式:JSON
  • • 字符编码:UTF-8

注意:API Key 和 API Secret 可在账户关联页获取,请确保妥善保管您的密钥信息。

认证方式

所有 API 请求必须携带认证信息。支持两种认证方式:

方式一:Header 直接认证(推荐用于测试)

在请求 Header 中直接携带 API Key 和 API Secret:

X-API-Key: mk_your_api_key_here
X-API-Secret: your_api_secret_here

方式二:签名认证(推荐用于生产环境)

使用 HMAC-SHA256 签名,更安全:

X-API-Key: mk_your_api_key_here
X-Timestamp: 1704067200000
X-Signature: 签名值

签名算法

// 签名字符串格式
signString = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + API_KEY

// 示例
method = "POST"
path = "/api/v1/videos"
timestamp = "1704067200000"  // 毫秒级时间戳
apiKey = "mk_your_api_key_here"

signString = "POST\n/api/v1/videos\n1704067200000\nmk_your_api_key_here"
signature = HMAC-SHA256(apiSecret, signString)

// 注意:时间戳有效期为 5 分钟

Node.js 签名示例

const crypto = require('crypto');

function generateSignature(method, path, apiKey, apiSecret) {
  const timestamp = Date.now().toString();
  const signString = `${method}\n${path}\n${timestamp}\n${apiKey}`;
  const signature = crypto
    .createHmac('sha256', apiSecret)
    .update(signString)
    .digest('hex');
  
  return { timestamp, signature };
}

// 使用示例
const { timestamp, signature } = generateSignature(
  'POST',
  '/api/v1/videos',
  'mk_your_api_key',
  'your_api_secret'
);

账户接口

获取 API Key 关联账户的信息,包括兼容余额、统一可用余额来源、套餐信息和用量统计。balance、lowBalanceThreshold、isLowBalance 保持原有语义;新增来源字段为向后兼容字段。

响应示例

{
  "success": true,
  "data": {
    "userId": "user_abc123",
    "email": "user@example.com",
    "name": "示例用户",
    "balance": 10000,
    "plan": "pro",
    "planExpiresAt": "2024-12-31T23:59:59Z",
    "usage": {
      "today": 150,
      "thisMonth": 3200
    },
    "lowBalanceThreshold": 1000,
    "isLowBalance": false,
    "personalSpendablePoints": 8000,
    "directedTransferPoints": 1500,
    "legacyPoolSpendablePoints": 500,
    "totalAvailablePoints": 10000,
    "historicalRefundCredits": 200
  }
}

视频任务

获取视频任务列表,支持分页和状态筛选。

请求参数

参数名类型必填说明
pagenumber否页码,默认 1
limitnumber否每页数量,默认 20,最大 100
statusstring否状态筛选:pending/processing/completed/failed

响应示例

{
  "success": true,
  "data": {
    "tasks": [
      {
        "id": "task_abc123",
        "title": "产品宣传视频",
        "status": "completed",
        "progress": 100,
        "duration": 15,
        "aspectRatio": "9:16",
        "videoUrl": "https://cdn.example.com/video.mp4",
        "thumbnailUrl": "https://cdn.example.com/thumb.jpg",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:05:00Z"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 20,
      "totalPages": 5
    }
  }
}

创建新的视频生成任务。任务将使用 API Key 关联账户的算力进行扣费。支持单图或多图上传,多图会自动拼接为多宫格图。

请求参数

参数名类型必填说明
descriptionstring是视频需求描述(必填)
imageUrlstring否商品图片 URL(与 imageUrls 二选一)
imageUrlsstring[]否多张商品图片 URL 数组,会自动拼接为多宫格图(与 imageUrl 二选一)
durationnumber否视频时长(秒),默认 10
aspectRatiostring否视频横纵比:9:16 / 16:9,默认 9:16
titlestring否视频标题(可选,不提供则自动生成)
callbackUrlstring否任务完成回调 URL

请求示例

// 单图上传
{
  "description": "展示智能保温杯的核心功能和特点",
  "imageUrl": "https://example.com/product.jpg",
  "duration": 15,
  "aspectRatio": "9:16"
}

// 多图上传(自动拼接为多宫格图)
{
  "description": "全方位展示产品细节和使用场景",
  "imageUrls": [
    "https://example.com/product-front.jpg",
    "https://example.com/product-side.jpg",
    "https://example.com/product-back.jpg",
    "https://example.com/product-detail.jpg"
  ],
  "duration": 15,
  "aspectRatio": "9:16",
  "title": "智能保温杯多角度展示"
}

响应示例

{
  "success": true,
  "data": {
    "id": "task_xyz789",
    "status": "pending",
    "imageCount": 4,
    "imageMerged": true,
    "callbackUrl": "https://your-server.com/webhook",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

获取指定视频任务的详细信息。

响应示例

{
  "success": true,
  "data": {
    "id": "task_abc123",
    "userId": "user_xyz",
    "title": "产品宣传视频",
    "imageUrl": "https://example.com/product.jpg",
    "description": "展示产品特性的短视频",
    "duration": 15,
    "aspectRatio": "9:16",
    "status": "completed",
    "progress": 100,
    "videoUrl": "https://cdn.example.com/video.mp4",
    "thumbnailUrl": "https://cdn.example.com/thumb.jpg",
    "productName": "智能手表 Pro",
    "errorMessage": null,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:05:00Z"
  }
}

删除指定的视频任务。

响应示例

{
  "success": true
}

模板管理

获取产品模板列表,支持分页。

请求参数

参数名类型必填说明
pagenumber否页码,默认 1
limitnumber否每页数量,默认 20,最大 100
userIdstring否按用户 ID 筛选

响应示例

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": "tpl_abc123",
        "userId": "user_xyz",
        "name": "电商产品模板",
        "imageUrl": "https://example.com/template.jpg",
        "productPosterUrl": null,
        "description": "适用于电商产品展示",
        "productName": "示例产品",
        "price": "99.00",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "limit": 20,
      "totalPages": 3
    }
  }
}

创建新的产品模板。

请求参数

参数名类型必填说明
userIdstring是用户 ID
namestring是模板名称
imageUrlstring否模板图片 URL
descriptionstring否模板描述
productNamestring否产品名称
pricestring否产品价格

请求示例

{
  "userId": "user_xyz",
  "name": "新品发布模板",
  "imageUrl": "https://example.com/template.jpg",
  "description": "适用于新品发布宣传",
  "productName": "旗舰产品",
  "price": "299.00"
}

响应示例

{
  "success": true,
  "data": {
    "id": "tpl_new123",
    "name": "新品发布模板",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Webhook 回调

当任务状态变更或账户发生重要事件时,系统会向您配置的回调 URL 发送 POST 请求。

回调请求格式

POST your_callback_url
Content-Type: application/json
X-Webhook-Signature: HMAC-SHA256签名
X-Webhook-Event: 事件类型
X-Webhook-Timestamp: 时间戳

事件类型

事件说明
video.completed任务完成
video.failed任务失败
account.low_balance余额预警(低于阈值)
account.insufficient_balance余额不足

任务完成回调示例

{
  "event": "video.completed",
  "timestamp": 1704067200,
  "data": {
    "taskId": "task_abc123",
    "status": "completed",
    "videoUrl": "https://cdn.example.com/video.mp4",
    "thumbnailUrl": "https://cdn.example.com/thumb.jpg",
    "duration": 15
  }
}

余额预警回调示例

{
  "event": "account.low_balance",
  "timestamp": 1704067200,
  "data": {
    "userId": "user_xyz",
    "currentBalance": 800,
    "threshold": 1000,
    "message": "关联账号算力余额不足,当前余额: 800,预警阈值: 1000"
  }
}

验证签名

请务必验证回调请求的签名,确保请求来源可信:

const crypto = require('crypto');

function verifyWebhookSignature(body, signature, apiSecret) {
  const expectedSignature = crypto
    .createHmac('sha256', apiSecret)
    .update(JSON.stringify(body))
    .digest('hex');
  
  return signature === expectedSignature;
}

// Express 示例
app.post('/webhook', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  
  if (!verifyWebhookSignature(req.body, signature, API_SECRET)) {
    return res.status(401).json({ error: '签名验证失败' });
  }
  
  // 处理事件
  const { event, data } = req.body;
  console.log('收到事件:', event, data);
  
  res.json({ success: true });
});

错误码

HTTP 状态码说明处理建议
200请求成功正常处理响应
400请求参数错误检查请求参数是否正确
401认证失败检查 API Key/Secret 或签名
403无权限 / IP 不在白名单检查权限配置或联系管理员
404资源不存在检查资源 ID 是否正确
429请求过于频繁 / 达到每日上限降低请求频率或等待次日重置
500服务器内部错误稍后重试或联系技术支持

SDK & 示例代码

完整调用示例(Node.js)

const crypto = require('crypto');

const API_KEY = 'mk_your_api_key';
const API_SECRET = 'your_api_secret';
const BASE_URL = 'https://aifroi.com/api/v1';

// 生成签名
function generateSignature(method, path) {
  const timestamp = Date.now().toString();
  const signString = `${method}\n${path}\n${timestamp}\n${API_KEY}`;
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(signString)
    .digest('hex');
  return { timestamp, signature };
}

// 创建视频任务
async function createVideoTask(data) {
  const path = '/api/v1/videos';
  const { timestamp, signature } = generateSignature('POST', path);
  
  const response = await fetch(BASE_URL + '/videos', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
    },
    body: JSON.stringify(data),
  });
  
  return response.json();
}

// 查询任务状态
async function getVideoTask(taskId) {
  const path = `/api/v1/videos/${taskId}`;
  const { timestamp, signature } = generateSignature('GET', path);
  
  const response = await fetch(BASE_URL + `/videos/${taskId}`, {
    headers: {
      'X-API-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
    },
  });
  
  return response.json();
}

// 使用示例
async function main() {
  // 创建任务
  const result = await createVideoTask({
    title: '产品宣传视频',
    imageUrl: 'https://example.com/product.jpg',
    duration: 15,
    aspectRatio: '9:16',
  });
  
  console.log('任务创建成功:', result.data.id);
  
  // 轮询查询状态
  let status = 'pending';
  while (status === 'pending' || status === 'processing') {
    await new Promise(resolve => setTimeout(resolve, 5000));
    const task = await getVideoTask(result.data.id);
    status = task.data.status;
    console.log('当前状态:', status);
  }
}

main();

cURL 示例

# 使用 Header 直接认证(测试用)
curl -X POST "https://aifroi.com/api/v1/videos" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mk_your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "title": "测试视频",
    "imageUrl": "https://example.com/image.jpg",
    "duration": 10
  }'

# 查询任务详情
curl "https://aifroi.com/api/v1/videos/task_abc123" \
  -H "X-API-Key: mk_your_api_key" \
  -H "X-API-Secret: your_api_secret"

技术支持:如有任何问题,请联系您的对接人员。