概述
欢迎使用开放平台 API。通过本 API,您可以程序化地调用视频生成服务, 实现视频任务的创建、查询和管理。
Base URL
https://dmjyai.vip/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 关联账户的信息,包括算力余额、套餐信息、用量统计等。
响应示例
{
"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
}
}视频任务
获取视频任务列表,支持分页和状态筛选。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
page | number | 否 | 页码,默认 1 |
limit | number | 否 | 每页数量,默认 20,最大 100 |
status | string | 否 | 状态筛选: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 关联账户的算力进行扣费。支持单图或多图上传,多图会自动拼接为多宫格图。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
description | string | 是 | 视频需求描述(必填) |
imageUrl | string | 否 | 商品图片 URL(与 imageUrls 二选一) |
imageUrls | string[] | 否 | 多张商品图片 URL 数组,会自动拼接为多宫格图(与 imageUrl 二选一) |
duration | number | 否 | 视频时长(秒),默认 10 |
aspectRatio | string | 否 | 视频横纵比:9:16 / 16:9,默认 9:16 |
title | string | 否 | 视频标题(可选,不提供则自动生成) |
callbackUrl | string | 否 | 任务完成回调 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
}模板管理
获取产品模板列表,支持分页。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
page | number | 否 | 页码,默认 1 |
limit | number | 否 | 每页数量,默认 20,最大 100 |
userId | string | 否 | 按用户 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
}
}
}创建新的产品模板。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
userId | string | 是 | 用户 ID |
name | string | 是 | 模板名称 |
imageUrl | string | 否 | 模板图片 URL |
description | string | 否 | 模板描述 |
productName | string | 否 | 产品名称 |
price | string | 否 | 产品价格 |
请求示例
{
"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: 时间戳事件类型
| 事件 | 说明 |
|---|---|
task.completed | 任务完成 |
task.failed | 任务失败 |
account.low_balance | 余额预警(低于阈值) |
account.insufficient_balance | 余额不足 |
任务完成回调示例
{
"event": "task.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://dmjyai.vip/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://dmjyai.vip/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://dmjyai.vip/api/v1/videos/task_abc123" \
-H "X-API-Key: mk_your_api_key" \
-H "X-API-Secret: your_api_secret"技术支持:如有任何问题,请联系您的对接人员。