操作指南

ScreenApp API和SDK文档

ScreenApps API使您能够自动转录、总结和分析视频和音频内容

作者 ScreenApp 团队

ScreenApp API 文档 v2.0.0

ScreenApp 的 API 使您能够自动转录、总结和分析视频和音频内容。非常适合希望大规模处理客户通话、培训视频和会议录音的企业。

主要用例

✨ 热门用例： 客户服务团队使用我们的 API 自动转录支持电话并生成摘要，然后通过 Webhook 同步到他们的 CRM。

在仪表板中获取 API 凭据 →

计划要求和 API 访问

要使用 ScreenApp API，您需要：

  1. 有效的 Business 计划订阅
  2. 来自您的 ScreenApp 仪表板的 API 凭据

获取您的 API 凭据

  1. 登录您的 ScreenApp 帐户
  2. 导航到设置 → 集成
  3. 在这里，您将找到：
    • API 令牌
    • 团队 ID

请确保这些凭据的安全，切勿公开分享。

快速开始

想立即开始吗？ 按照以下步骤将 ScreenApp 集成到您的网站中：

1. 安装插件

将此代码添加到您网站的 HTML 中：

<script>
  // Plugin installation code here
</script>

2. 添加触发按钮

向您的页面添加按钮或触发元素：

<button onclick="loadScreenApp()">Start Recording</button>

3. 配置回调

自定义回调函数以处理录制完成：

function callback({ id, url }) {
  // Example: Send to your backend
  fetch('/api/recordings', {
    method: 'POST',
    body: JSON.stringify({ recordingId: id, recordingUrl: url })
  });
  
  // Example: Update UI
  document.getElementById('status').innerHTML = 
    `Recording saved! View it at ${url}`;
}

身份验证

所有 API 请求都需要身份验证。 ScreenApp 使用基于令牌的身份验证以及特定于团队的标识符。

您需要的凭据

身份验证示例

curl -X POST "https://api.screenapp.io/v2/files/upload" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID"

身份验证端点

GET /auth/google

重定向到 Google 进行身份验证

查询参数：

GET /auth/facebook

重定向到 Facebook 进行身份验证

查询参数：

核心概念

在深入研究特定端点之前，让我们了解 ScreenApp 中的关键概念：

  1. 录音：可以上传和处理的视频和音频捕获
  2. 团队：可以共享和管理录音的群组
  3. Webhook：用于录音事件和处理结果的实时通知
  4. 标签：可以附加到录音、团队或用户配置文件的元数据

API 参考

团队管理

POST /team/{teamId}/tag

将标签添加到团队

路径参数：

请求正文：

{
  "key": "color",
  "value": "red"
}

DELETE /team/{teamId}/tag

从团队中删除标签

路径参数：

请求正文：

{
  "key": "color"
}

团队 Webhook 集成

POST /team/{teamId}/integrations/webhook

为团队注册一个新的 Webhook URL

路径参数：

请求正文：

{
  "url": "https://example.com/webhook",
  "name": "My Webhook"
}

响应：

DELETE /team/{teamId}/integrations/webhook

取消注册团队的 Webhook URL

路径参数：

查询参数：

响应：

GET /team/{teamId}/integrations/zapier/sample/list

获取 Zapier 的示例数据作为数组

路径参数：

响应：

用户集成

POST /integrations/webhook

为用户注册一个新的 Webhook

请求正文：

{
  "url": "https://example.com/webhook",
  "name": "My Webhook"
}

响应：

DELETE /integrations/webhook

为用户注销 Webhook

查询参数：

响应：

Webhook 事件

您的 Webhook 端点将收到以下格式的事件：

{
  "event": "recording.completed",
  "fileId": "file789",
  "teamId": "team123",
  "data": {
    "url": "https://screenapp.io/recording/file789",
    "duration": 300,
    "status": "processed"
  }
}

常见事件包括：

文件管理

POST /files/{fileId}/tag

将标签添加到文件

路径参数：

请求正文：

{
  "key": "color",
  "value": "red"
}

DELETE /files/{fileId}/tag

从文件中删除标签

路径参数：

请求正文：

{
  "key": "color"
}

POST /files/{fileId}/ask/multimodal

使用多个 AI 模型询问有关文件的问题

路径参数：

请求正文：

{
  "promptText": "What are the key points discussed?",
  "mediaAnalysisOptions": {
    "transcript": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "video": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "screenshots": {
      "timestamps": [30, 60, 90]
    }
  }
}

响应：

文件上传

POST /files/upload/{teamId}/{folderId}/url

生成文件上传的预签名 URL

路径参数：

请求正文：

{
  "files": [
    {
      "contentType": "video/mp4",
      "name": "meeting-recording.mp4"
    }
  ]
}

响应：

POST /files/upload/{teamId}/{folderId}/finalize

完成上传的文件

路径参数：

请求正文：

{
  "file": {
    "fileId": "file123",
    "contentType": "video/mp4",
    "name": "Sales Call",
    "description": "Weekly sales call with customer",
    "recorderName": "John Doe",
    "recorderEmail": "john.doe@example.com"
  }
}

响应：

分段上传（适用于大文件）

PUT /files/upload/multipart/init/{teamId}/{folderId}

初始化大文件的分段上传

路径参数：

请求正文：

{
  "contentType": "video/mp4"
}

响应：

响应示例：

{
  "success": true,
  "data": {
    "fileId": "file789",
    "uploadId": "upload123"
  }
}

PUT /files/upload/multipart/url/{teamId}/{folderId}/{fileId}/{uploadId}/{partNumber}

获取特定部分的上载 URL

路径参数：

请求正文：

{
  "contentType": "video/mp4"
}

响应：

响应示例：

{
  "success": true,
  "data": {
    "uploadUrl": "https://presigned-s3-url.com/part1"
  }
}

PUT /files/upload/multipart/finalize/{teamId}/{folderId}/{fileId}/{uploadId}

完成分段上传

路径参数：

请求正文：

{
  "file": {
    "contentType": "video/mp4",
    "recorderName": "John Doe",
    "recorderEmail": "john@example.com",
    "name": "My Recording",
    "description": "A recorded video session",
    "notes": [
      {
        "text": "Important point discussed",
        "timestamp": 1234567890
      }
    ]
  }
}

响应：

PUT /files/upload/multipart/fallback/{teamId}/{folderId}/{fileId}/{partNumber}

通过后端上传文件部分（后备）

路径参数：

表单数据：

响应：

帐户管理

POST /v2/account/tag

向已验证的用户添加标签

请求正文：

{
  "key": "color",
  "value": "red"
}

响应：

PUT /account/profile

更新经过身份验证的用户的个人资料

请求正文：

{
  "firstName": "John",
  "lastName": "Doe",
  "name": "John Doe",
  "gender": "male",
  "userType": "user",
  "company": "Acme Inc",
  "role": "Developer",
  "goals": "Learn new technologies",
  "phoneNumber": "+1234567890",
  "location": "San Francisco, CA",
  "website": "https://example.com",
  "picture": "https://example.com/avatar.jpg",
  "provider": "local",
  "providerId": "12345",
  "primaryField": "development"
}

响应：

高级功能

AI 分析

使用 AI 分析您的录音以获取见解：

// Request AI analysis of a recording
const analysis = await fetch(`/v2/files/${fileId}/ask/multimodal`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptText: "What are the key discussion points?",
    mediaAnalysisOptions: {
      transcript: {
        segments: [{ start: 0, end: 300 }]
      },
      video: {
        segments: [{ start: 0, end: 300 }]
      }
    }
  })
});

批量操作

高效管理多个录音：

// Tag multiple recordings
async function batchTag(fileIds, tag) {
  const promises = fileIds.map(fileId => 
    fetch(`/v2/files/${fileId}/tag`, {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(tag)
    })
  );
  await Promise.all(promises);
}

错误处理

常见错误代码

错误响应格式

错误响应通常遵循以下格式：

{
  "success": false,
  "message": "Detailed error message"
}

示例

设置团队 Webhook

Webhook 允许您在录音处理完毕后接收实时更新：

// Register a new webhook for your team
async function registerTeamWebhook(teamId, webhookUrl, webhookName) {
  const response = await fetch(`/v2/team/${teamId}/integrations/webhook`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: webhookUrl,
      name: webhookName
    })
  });
  return await response.json();
}

// Example usage
const result = await registerTeamWebhook(
  'team123',
  'https://your-domain.com/webhooks/screenapp',
  'Recording Updates'
);

上传和处理大型文件

对于大于 100MB 的文件，请使用分段上传流程：

// 1. Initialize upload
const initResponse = await fetch(`/v2/files/upload/multipart/init/${teamId}/${folderId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    contentType: 'video/mp4'
  })
});

const { data: { fileId, uploadId } } = await initResponse.json();

// 2. Split file into chunks and upload each part
const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB chunks
const totalParts = Math.ceil(file.size / CHUNK_SIZE);

for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
  // Get upload URL for this part
  const urlResponse = await fetch(
    `/v2/files/upload/multipart/url/${teamId}/${folderId}/${fileId}/${uploadId}/${partNumber}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        contentType: 'video/mp4'
      })
    }
  );
  
  const { data: { uploadUrl } } = await urlResponse.json();
  
  // Create the chunk from the file
  const start = (partNumber - 1) * CHUNK_SIZE;
  const end = Math.min(start + CHUNK_SIZE, file.size);
  const chunk = file.slice(start, end);
  
  // Upload the chunk directly to S3
  await fetch(uploadUrl, {
    method: 'PUT',
    body: chunk,
    headers: {
      'Content-Type': 'video/mp4'
    }
  });
}

// 3. Finalize the upload
const finalizeResponse = await fetch(
  `/v2/files/upload/multipart/finalize/${teamId}/${folderId}/${fileId}/${uploadId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      file: {
        contentType: 'video/mp4',
        name: 'Customer Meeting Recording',
        description: 'Quarterly review with client',
        recorderName: 'Jane Smith',
        recorderEmail: 'jane@example.com'
      }
    })
  }
);

在仪表板中获取 API 凭据 →