心想AI 开放 API

通过 RESTful API 将 AI 视频生成能力集成到您的应用中,实现自动化视频创作流程

https://www.ixinxiang.cn/api/v1

1. 获取密钥

在控制台创建 API 密钥,支持设置权限、配额和 IP 白名单

创建密钥

2. 调用接口

使用标准 HTTP 请求调用 API,支持所有主流编程语言

查看接口

3. 接收回调

配置 Webhook 地址,视频生成完成后自动接收通知

了解回调

认证方式

所有 API 请求都需要在 HTTP Header 中携带 API 密钥进行身份验证:

请求头格式
http
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx
安全提示:请妥善保管您的 API 密钥,不要在客户端代码或公共仓库中暴露。 如果密钥泄露,请立即在控制台禁用并重新生成。

基础信息

https://www.ixinxiang.cn/api/v1

application/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

使用限制

  • 请求频率限制: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: 参考图片用于保持视频中人物或场景的一致性。上传一张人物照片后,生成的视频将尽可能保持该人物形象。

准备好开始了吗?

创建您的第一个 API 密钥,开始构建自动化视频生成工作流