跳转到主要内容

欢迎使用 Sora2API

Sora2API 让您能够使用先进的 AI 模型生成高质量的视频内容。无论您是在构建应用、自动化工作流程还是创建内容,我们的API都为AI视频生成提供了简单可靠的访问方式。

身份验证

所有 API 请求都需要使用 Bearer 令牌进行身份验证。请从 API 密钥管理页面 获取您的 API 密钥。
请妥善保管您的 API 密钥,切勿公开分享。如果怀疑密钥泄露,请立即重置。

API 基础 URL

https://api.sora2api.ai

身份验证请求头

Authorization: Bearer YOUR_API_KEY

快速开始指南

第一步:生成您的第一个视频

从一个简单的文本生成视频请求开始:
async function generateVideo() {
  try {
    const response = await fetch('https://api.sora2api.ai/api/v1/sora2/generate', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt: '一只可爱的小猫在花园里玩耍,阳光明媚的春天',
        aspectRatio: 'landscape',
        quality: 'hd'
      })
    });
    
    const data = await response.json();
    
    if (response.ok && data.code === 200) {
      console.log('任务已提交:', data);
      console.log('任务ID:', data.data.taskId);
      return data.data.taskId;
    } else {
      console.error('请求失败:', data.msg || '未知错误');
      return null;
    }
  } catch (error) {
    console.error('错误:', error.message);
    return null;
  }
}

generateVideo();

第二步:检查任务状态

使用返回的任务ID检查生成状态:
curl -X GET "https://api.sora2api.ai/api/v1/sora2/record-info?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应格式

成功响应:
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "sora2_task_abcdef123456"
  }
}
任务状态响应:
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "sora2_task_abcdef123456",
    "paramJson": "{\"prompt\":\"一只可爱的小猫在花园里玩耍,阳光明媚的春天\",\"aspectRatio\":\"landscape\",\"quality\":\"hd\"}",
    "completeTime": "2024-03-20 10:30:00",
    "response": {
      "imageUrl": "https://cdn.sora2api.ai/videos/example_video.mp4"
    },
    "successFlag": 1,
    "errorCode": 0,
    "errorMessage": null,
    "createTime": "2024-03-20 10:25:00"
  }
}

生成模式

  • 文本生成视频
  • 图像生成视频
  • 添加水印
从文本描述生成视频:
{
  "prompt": "一只可爱的小猫在花园里玩耍,阳光明媚的春天",
  "aspectRatio": "landscape",
  "quality": "hd"
}

视频比例

为您的需求选择合适的宽高比:

Landscape (横屏)

适用场景高清视频、桌面壁纸、横向观看的内容

Portrait (竖屏)

适用场景手机壁纸、短视频、竖向观看的内容

清晰度选项

Standard

标准清晰度适合快速生成和预览,节省积分

HD

高清高质量输出,适合正式发布和商业用途

关键参数

prompt
string
required
对所需视频内容的文本描述。为获得最佳结果,请具体和描述性地表达。更好提示词的技巧:
  • 包含场景描述(如”花园”、“海滩”、“城市街道”)
  • 指定主体动作(如”奔跑”、“跳舞”、“飞翔”)
  • 添加氛围描述(如”阳光明媚”、“神秘夜晚”、“温馨氛围”)
aspectRatio
string
输出视频宽高比。可选择:
  • landscape - 横屏(适合桌面观看)
  • portrait - 竖屏(适合手机观看)
quality
string
视频清晰度:
  • standard - 标准清晰度
  • hd - 高清
imageUrls
array
图片链接数组,用于图像生成视频模式。注意事项:
  • 图片必须是可访问的公网URL
  • 支持常见图片格式(JPG、PNG等)
watermark
string
水印文字,将显示在生成的视频上。注意: 可选参数,如不需要水印可省略此字段。
callBackUrl
string
回调地址,用于接收任务完成通知。建议: 在生产环境中使用回调而非轮询,可提高效率。

完整工作流程示例

以下是一个生成视频并等待完成的完整示例:
  • JavaScript
  • Python
class Sora2API {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.sora2api.ai/api/v1/sora2';
  }
  
  async generateVideo(options) {
    const response = await fetch(`${this.baseUrl}/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(options)
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`生成失败: ${result.msg || '未知错误'}`);
    }
    
    return result.data.taskId;
  }
  
  async waitForCompletion(taskId, maxWaitTime = 600000) { // 最长等待10分钟
    const startTime = Date.now();
    
    while (Date.now() - startTime < maxWaitTime) {
      const status = await this.getTaskStatus(taskId);
      
      switch (status.successFlag) {
        case 0:
          console.log('任务生成中,继续等待...');
          break;
          
        case 1:
          console.log('生成成功完成!');
          return status.response;
          
        case 2:
          const taskError = status.errorMessage || '任务创建失败';
          console.error('任务创建失败:', taskError);
          if (status.errorCode) {
            console.error('错误代码:', status.errorCode);
          }
          throw new Error(taskError);
          
        case 3:
          const generateError = status.errorMessage || '任务生成失败';
          console.error('生成失败:', generateError);
          if (status.errorCode) {
            console.error('错误代码:', status.errorCode);
          }
          throw new Error(generateError);
          
        default:
          console.log(`未知状态: ${status.successFlag}`);
          if (status.errorMessage) {
            console.error('错误信息:', status.errorMessage);
          }
          break;
      }
      
      // 等待30秒后再次检查
      await new Promise(resolve => setTimeout(resolve, 30000));
    }
    
    throw new Error('生成超时');
  }
  
  async getTaskStatus(taskId) {
    const response = await fetch(`${this.baseUrl}/record-info?taskId=${taskId}`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`查询状态失败: ${result.msg || '未知错误'}`);
    }
    
    return result.data;
  }
}

// 使用示例
async function main() {
  const api = new Sora2API('YOUR_API_KEY');
  
  try {
    // 文本生成视频
    console.log('开始视频生成...');
    const taskId = await api.generateVideo({
      prompt: '一只可爱的小猫在花园里玩耍,阳光明媚的春天,镜头缓缓推进',
      aspectRatio: 'landscape',
      quality: 'hd',
      watermark: '我的视频'
    });
    
    // 等待完成
    console.log(`任务ID: ${taskId}。等待完成...`);
    const result = await api.waitForCompletion(taskId);
    
    console.log('视频生成成功!');
    console.log('视频URL:', result.imageUrl);
    
  } catch (error) {
    console.error('错误:', error.message);
  }
}

main();

使用回调的异步处理

对于生产应用,使用回调而不是轮询:
{
  "prompt": "一只可爱的小猫在花园里玩耍,阳光明媚的春天",
  "aspectRatio": "landscape",
  "quality": "hd",
  "callBackUrl": "https://your-app.com/webhook/sora2-callback"
}
当生成完成时,系统会将结果POST到您的回调URL。

了解更多关于回调

实现和处理 Sora2API 回调的完整指南

最佳实践

  • 在提示词中要具体和描述性
  • 包含场景、动作和氛围细节
  • 描述想要的镜头运动(如”缓慢推进”、“环绕拍摄”)
  • 测试不同的提示词变化以找到最佳效果
  • 使用回调而不是频繁轮询
  • 实施适当的错误处理和重试逻辑
  • 在可能时缓存结果
  • 根据需求选择适当的清晰度
  • 使用标准清晰度进行测试和预览
  • 仅在需要时使用高清选项
  • 定期监控您的积分使用情况
  • 在您的应用中设置使用警报
  • 始终检查响应状态码
  • 通过 successFlag 判断任务真实状态
  • 为重试实施指数退避
  • 优雅地处理速率限制
  • 记录错误以进行调试和监控

状态码

200
成功
请求成功处理
400
错误请求
无效的请求参数或格式错误的JSON
401
未授权
缺少或无效的API密钥
402
积分不足
账户没有足够的积分进行操作
429
速率限制
请求过多 - 实施退避策略
500
服务器错误
内部服务器错误 - 如果持续存在请联系支持

生成任务状态说明

successFlag: 0
生成中
任务正在处理中
successFlag: 1
成功
任务成功完成
successFlag: 2
创建任务失败
任务创建失败
successFlag: 3
生成失败
任务创建成功但生成失败

视频存储和保留

生成的视频文件在删除前保留 15天。请在此时间范围内下载并保存您的视频。
  • 视频URL在生成后15天内保持可访问
  • 规划您的工作流程以在过期前下载或处理视频
  • 考虑为生产使用实施自动下载系统

下一步

支持

需要帮助吗?我们的技术支持团队随时为您提供帮助。

准备开始生成令人惊叹的AI视频了吗?获取您的API密钥,立即开始创作!