心想AI 开放 API
通过 RESTful API 将 AI 视频生成能力集成到您的应用中,实现自动化视频创作流程
https://www.ixinxiang.cn/api/v1
认证方式
所有 API 请求都需要在 HTTP Header 中携带 API 密钥进行身份验证:
请求头格式
http
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx安全提示:请妥善保管您的 API 密钥,不要在客户端代码或公共仓库中暴露。 如果密钥泄露,请立即在控制台禁用并重新生成。
基础信息
https://www.ixinxiang.cn/api/v1application/json
UTF-8
HTTPS 协议:所有 API 请求必须使用 HTTPS 协议,HTTP 请求将被拒绝。
API 权限
创建 API 密钥时可以设置以下权限:
| 权限标识 | 说明 | 关联接口 |
|---|---|---|
credits:read | 查询积分余额 | GET /credits/balance |
video:create | 创建视频生成任务 | POST /videos/generate |
video:read | 查询视频状态和列表 | GET /videos, GET /videos/{taskId}/status |
API 接口参考
查询当前账户的积分余额和 API 密钥配额使用情况。
需要权限:
credits:read请求示例
cURL
bash
curl -X GET "https://www.ixinxiang.cn/api/v1/credits/balance" \
-H "Authorization: Bearer sk_live_xxxxxxxx"响应示例
成功响应 (200)
json
{
"success": true,
"data": {
"credits": 1000,
"apiKeyQuota": {
"monthly": 500,
"used": 120,
"remaining": 380
}
}
}无配额限制的响应
json
{
"success": true,
"data": {
"credits": 1000,
"apiKeyQuota": null
}
}Webhook 回调
在创建视频生成任务时,您可以指定 callbackUrl 参数。 当视频生成完成(成功或失败)后,系统会向该地址发送 POST 请求。
回调请求格式
成功回调 (event: video.completed)
json
{
"event": "video.completed",
"timestamp": "2024-01-15T10:32:00.000Z",
"data": {
"taskId": "clxxxxxxxxxxxxxxxxxx",
"projectId": "clxxxxxxxxxxxxxxxxxx",
"status": "completed",
"videoUrl": "https://xinxiang-oss.oss-cn-hangzhou.aliyuncs.com/videos/xxx.mp4",
"thumbnailUrl": "https://xinxiang-oss.oss-cn-hangzhou.aliyuncs.com/thumbnails/xxx.jpg",
"creditsUsed": 50
}
}失败回调 (event: video.failed)
json
{
"event": "video.failed",
"timestamp": "2024-01-15T10:32:00.000Z",
"data": {
"taskId": "clxxxxxxxxxxxxxxxxxx",
"projectId": "clxxxxxxxxxxxxxxxxxx",
"status": "failed",
"errorMessage": "视频生成失败:服务暂时不可用",
"creditsRefunded": 50
}
}重要:请确保您的回调接口在 5 秒内返回 2xx 状态码。 如果回调失败,系统会在 1 分钟、5 分钟、30 分钟后进行最多 3 次重试。
错误处理
API 使用标准 HTTP 状态码表示请求结果。错误响应会包含详细的错误信息。
| 状态码 | 说明 |
|---|---|
200 | 请求成功 |
400 | 请求参数错误或内容审核未通过 |
401 | 未授权 - API 密钥无效、缺失或已禁用 |
402 | 积分不足 |
403 | 权限不足或 IP 不在白名单 |
404 | 资源不存在(用户/任务不存在) |
429 | 请求过于频繁或 API 密钥月度配额已用完 |
500 | 服务器内部错误 |
错误响应格式
{
"success": false,
"error": "错误描述信息",
"data": {
// 可选的附加错误信息
}
}代码示例
Python
import requests
import time
API_KEY = "sk_live_xxxxxxxxxxxxxxxx"
BASE_URL = "https://www.ixinxiang.cn/api/v1"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# 1. 查询余额
balance_res = requests.get(f"{BASE_URL}/credits/balance", headers=headers)
print(f"当前余额: {balance_res.json()['data']['credits']} 积分")
# 2. 创建视频生成任务
response = requests.post(
f"{BASE_URL}/videos/generate",
headers=headers,
json={
"title": "产品介绍视频",
"script": "这是一款革命性的产品,它将改变您的生活方式...",
"orientation": "portrait",
"duration": 10,
"callbackUrl": "https://your-site.com/webhook"
}
)
result = response.json()
if not result["success"]:
print(f"创建失败: {result['error']}")
exit(1)
task_id = result["data"]["taskId"]
print(f"任务创建成功: {task_id}")
# 3. 轮询查询生成状态
while True:
status_res = requests.get(f"{BASE_URL}/videos/{task_id}/status", headers=headers)
data = status_res.json()["data"]
print(f"状态: {data['status']}, 进度: {data['progress']}%")
if data["status"] == "completed":
print(f"视频生成完成!")
print(f"视频地址: {data['videoUrl']}")
break
elif data["status"] == "failed":
print(f"生成失败: {data.get('errorMessage', '未知错误')}")
break
time.sleep(10) # 每 10 秒查询一次Node.js / TypeScript
const API_KEY = 'sk_live_xxxxxxxxxxxxxxxx';
const BASE_URL = 'https://www.ixinxiang.cn/api/v1';
const headers = {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
};
// 创建视频并轮询状态
async function createVideoAndWait() {
// 1. 查询余额
const balanceRes = await fetch(`${BASE_URL}/credits/balance`, { headers });
const balanceData = await balanceRes.json();
console.log(`当前余额: ${balanceData.data.credits} 积分`);
// 2. 创建视频生成任务
const createRes = await fetch(`${BASE_URL}/videos/generate`, {
method: 'POST',
headers,
body: JSON.stringify({
title: '产品介绍视频',
script: '这是一款革命性的产品,它将改变您的生活方式...',
orientation: 'portrait',
duration: 10,
callbackUrl: 'https://your-site.com/webhook'
})
});
const createData = await createRes.json();
if (!createData.success) {
throw new Error(`创建失败: ${createData.error}`);
}
const taskId = createData.data.taskId;
console.log(`任务创建成功: ${taskId}`);
// 3. 轮询查询状态
const checkStatus = async (): Promise<string> => {
const statusRes = await fetch(`${BASE_URL}/videos/${taskId}/status`, { headers });
const { data } = await statusRes.json();
console.log(`状态: ${data.status}, 进度: ${data.progress}%`);
if (data.status === 'completed') {
console.log('视频生成完成!');
console.log(`视频地址: ${data.videoUrl}`);
return data.videoUrl;
} else if (data.status === 'failed') {
throw new Error(`生成失败: ${data.errorMessage || '未知错误'}`);
} else {
// 10秒后重试
await new Promise(resolve => setTimeout(resolve, 10000));
return checkStatus();
}
};
return checkStatus();
}
createVideoAndWait()
.then(url => console.log('最终视频地址:', url))
.catch(err => console.error(err));PHP
<?php
$apiKey = 'sk_live_xxxxxxxxxxxxxxxx';
$baseUrl = 'https://www.ixinxiang.cn/api/v1';
function makeRequest($url, $method = 'GET', $data = null) {
global $apiKey;
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json'
]);
if ($method === 'POST') {
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
}
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
// 1. 查询余额
$balance = makeRequest($baseUrl . '/credits/balance');
echo "当前余额: " . $balance['data']['credits'] . " 积分\n";
// 2. 创建视频生成任务
$result = makeRequest($baseUrl . '/videos/generate', 'POST', [
'title' => '产品介绍视频',
'script' => '这是一款革命性的产品,它将改变您的生活方式...',
'orientation' => 'portrait',
'duration' => 10
]);
if (!$result['success']) {
die("创建失败: " . $result['error']);
}
$taskId = $result['data']['taskId'];
echo "任务创建成功: $taskId\n";
// 3. 轮询查询状态
while (true) {
$status = makeRequest($baseUrl . '/videos/' . $taskId . '/status');
$data = $status['data'];
echo "状态: {$data['status']}, 进度: {$data['progress']}%\n";
if ($data['status'] === 'completed') {
echo "视频生成完成!\n";
echo "视频地址: {$data['videoUrl']}\n";
break;
} elseif ($data['status'] === 'failed') {
echo "生成失败: " . ($data['errorMessage'] ?? '未知错误') . "\n";
break;
}
sleep(10);
}费用说明
API 调用按积分计费,不同参数配置消耗的积分不同(积分兑换比例:1 元 = 100 积分):
| 画质 | 方向 | 时长 | 积分消耗 | 约合人民币 |
|---|---|---|---|---|
| 标清 (720P) | 竖屏 (9:16) | 10秒 | 50 积分 | ¥0.50 |
| 标清 (720P) | 竖屏 (9:16) | 15秒 | 75 积分 | ¥0.75 |
| 标清 (720P) | 横屏 (16:9) | 10秒 | 60 积分 | ¥0.60 |
| 标清 (720P) | 横屏 (16:9) | 15秒 | 90 积分 | ¥0.90 |
自动退款:创建任务时会预扣积分,如果生成失败,积分将自动全额退还到您的账户。
计费公式:费用 = 基础费用 × 时长系数
10秒时长系数 = 1.0,15秒时长系数 = 1.5
10秒时长系数 = 1.0,15秒时长系数 = 1.5
使用限制
- 请求频率限制:100 次/分钟
- 脚本长度限制:单个视频脚本最大 5000 字符
- 并发任务限制:同时进行的生成任务最多 10 个
- 文件保留时间:视频文件保留 30 天(请及时下载备份)
- 视频时长选项:当前支持 10 秒和 15 秒
- 月度配额:可在创建 API 密钥时设置月度配额限制
如需更高的配额限制,请联系我们的商务团队获取企业级方案:support@ixinxiang.cn
常见问题
Q: 视频生成需要多长时间?
A: 通常 60-120 秒内完成生成。高峰期可能需要 2-3 分钟。建议使用 Webhook 回调而非轮询来获取完成通知。
Q: 生成失败会扣除积分吗?
A: 不会。创建任务时会预扣积分,如果生成失败,积分会自动全额退还到您的账户。
Q: 如何提高内容审核通过率?
A: 请确保脚本内容健康合规,避免涉及政治敏感、色情低俗、暴力血腥等内容。轻微违规内容系统会尝试自动修正。
Q: 生成的视频可以商用吗?
A: 可以。您通过 API 生成的视频版权归您所有,可用于任何合法的商业用途。
Q: 参考图片有什么用?
A: 参考图片用于保持视频中人物或场景的一致性。上传一张人物照片后,生成的视频将尽可能保持该人物形象。