ScreenApp APIドキュメント v2.0.0
ScreenAppのAPIを使用すると、ビデオおよびオーディオコンテンツを自動的に文字起こし、要約、分析できます。顧客の通話、トレーニングビデオ、会議の録音を大規模に処理したい企業に最適です。
主なユースケース
- 自動文字起こしと要約: あらゆるビデオまたはオーディオを検索可能なテキストと簡潔な要約に変換します。カスタマーサービスチーム、教育機関、コンテンツクリエイターに最適です。
- ナレッジマネジメント: 自動文字起こし、要約、AIを活用したインサイトを備えたビデオコンテンツの検索可能なリポジトリを構築します。トレーニング資料や企業ナレッジベースに最適です。
- リアルタイム処理: 録音の処理が完了するとすぐに、Webhook経由で文字起こしと要約を受け取ります。CRMシステムやカスタマーサービスプラットフォームとの統合に最適です。
- 組み込み録音: 画面と音声の両方をキャプチャできる埋め込み可能なレコーダーを使用して、プロフェッショナルグレードの録音機能をアプリケーションに追加します。
✨ 人気のユースケース: カスタマーサービスチームは、当社のAPIを使用してサポート通話を自動的に文字起こしし、要約を生成します。これらの要約は、Webhookを通じてCRMに同期されます。
プランの要件とAPIアクセス
ScreenApp APIを使用するには、以下が必要です。
- アクティブなビジネスプランのサブスクリプション
- ScreenAppダッシュボードからのAPI認証情報
API認証情報の取得
- ScreenAppアカウントにログインします
- 設定 → 統合に移動します
- ここに以下があります:
- APIトークン
- チームID
これらの認証情報を安全に保ち、公開しないでください。
クイックスタート
すぐに始めたいですか?以下の手順に従って、ScreenAppをWebサイトに統合します。
1. プラグインのインストール
このコードをWebサイトのHTMLに追加します。
<script>
// プラグインのインストールコードをここに記述します
</script>
2. トリガーボタンの追加
ボタンまたはトリガー要素をページに追加します。
<button onclick="loadScreenApp()">録画を開始</button>
3. コールバックの設定
コールバック関数をカスタマイズして、録画完了を処理します。
function callback({ id, url }) {
// 例: バックエンドに送信する
fetch('/api/recordings', {
method: 'POST',
body: JSON.stringify({ recordingId: id, recordingUrl: url })
});
// 例: UIの更新
document.getElementById('status').innerHTML =
`録画が保存されました! ${url} で表示できます`;
}
認証
すべてのAPIリクエストには認証が必要です。ScreenAppは、チーム固有の識別子とともにトークンベースの認証を使用します。
必要な認証情報
- APIトークン: 秘密のAPIキー
- チームID: 一意のチーム識別子
認証の例
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にリダイレクト
クエリパラメータ:
redirectUrl
- 認証成功後にユーザーをリダイレクトするエンコードされたURLreferrerUrl
- エンコードされたリファラーURLintent
- ユーザーの意図(例: “signup”)
GET /auth/facebook
認証のためにFacebookにリダイレクト
クエリパラメータ:
redirectUrl
- 認証成功後にユーザーをリダイレクトするエンコードされたURLreferrerUrl
- エンコードされたリファラーURLintent
- ユーザーの意図(例: “signup”)
コアコンセプト
特定のエンドポイントに入る前に、ScreenAppの主要な概念を理解しましょう。
- 録音: アップロードおよび処理できるビデオおよびオーディオキャプチャ
- チーム: 録音を共有および管理できるグループ
- Webhook: 録音イベントおよび処理結果のリアルタイム通知
- タグ: 録音、チーム、またはユーザープロファイルにアタッチできるメタデータ
APIリファレンス
チーム管理
POST /team/{teamId}/tag
チームにタグを追加
パスパラメータ:
teamId
- チームのID
リクエストボディ:
{
"key": "color",
"value": "red"
}
DELETE /team/{teamId}/tag
チームからタグを削除
パスパラメータ:
teamId
- チームのID
リクエストボディ:
{
"key": "color"
}
チームWebhook統合
POST /team/{teamId}/integrations/webhook
チームの新しいWebhook URLを登録
パスパラメータ:
teamId
- チームのID
リクエストボディ:
{
"url": "https://example.com/webhook",
"name": "My Webhook"
}
レスポンス:
200
- Webhookが正常に登録されました400
- 無効なリクエストボディ500
- 内部サーバーエラー
DELETE /team/{teamId}/integrations/webhook
チームのWebhook URLの登録を解除
パスパラメータ:
teamId
- チームのID
クエリパラメータ:
url
- 登録を解除するWebhook URL
レスポンス:
200
- Webhookが正常に登録解除されました400
- 無効なリクエスト404
- Webhook URLが見つかりません500
- 内部サーバーエラー
GET /team/{teamId}/integrations/zapier/sample/list
Zapierのサンプルデータを配列として取得
パスパラメータ:
teamId
- チームのID
レスポンス:
200
- サンプルデータが正常に取得されました404
- サンプルファイルが見つかりません
ユーザー統合
POST /integrations/webhook
ユーザーの新しいWebhookを登録
リクエストボディ:
{
"url": "https://example.com/webhook",
"name": "My Webhook"
}
レスポンス:
200
- Webhookが正常に登録されました400
- 無効なリクエストボディ
DELETE /integrations/webhook
ユーザーのWebhookの登録を解除
クエリパラメータ:
url
- 登録を解除するWebhook URL
レスポンス:
200
- Webhookが正常に登録解除されました400
- 無効なリクエスト404
- Webhook URLが見つかりません
Webhookイベント
Webhookエンドポイントは、次の形式でイベントを受信します。
{
"event": "recording.completed",
"fileId": "file789",
"teamId": "team123",
"data": {
"url": "https://screenapp.io/recording/file789",
"duration": 300,
"status": "processed"
}
}
一般的なイベントは次のとおりです。
recording.started
recording.completed
recording.processed
recording.failed
ファイル管理
POST /files/{fileId}/tag
ファイルにタグを追加
パスパラメータ:
fileId
- ファイルのID
リクエストボディ:
{
"key": "color",
"value": "red"
}
DELETE /files/{fileId}/tag
ファイルからタグを削除
パスパラメータ:
fileId
- ファイルのID
リクエストボディ:
{
"key": "color"
}
POST /files/{fileId}/ask/multimodal
複数のAIモデルを使用してファイルに関する質問をする
パスパラメータ:
fileId
- 分析するファイルのID
リクエストボディ:
{
"promptText": "主な議論点は何ですか?",
"mediaAnalysisOptions": {
"transcript": {
"segments": [
{
"start": 0,
"end": 120
}
]
},
"video": {
"segments": [
{
"start": 0,
"end": 120
}
]
},
"screenshots": {
"timestamps": [30, 60, 90]
}
}
}
レスポンス:
200
- 質問が正常に処理されました403
- AI使用制限を超えました500
- サーバーエラー
ファイルのアップロード
POST /files/upload/{teamId}/{folderId}/url
ファイルのアップロード用に事前署名付きURLを生成
パスパラメータ:
teamId
- チームのIDfolderId
- フォルダのID
リクエストボディ:
{
"files": [
{
"contentType": "video/mp4",
"name": "meeting-recording.mp4"
}
]
}
レスポンス:
200
- アップロードURLが正常に生成されました400
- 無効なリクエストパラメータ500
- サーバーエラー
POST /files/upload/{teamId}/{folderId}/finalize
アップロードされたファイルをファイナライズ
パスパラメータ:
teamId
- チームのIDfolderId
- フォルダのID
リクエストボディ:
{
"file": {
"fileId": "file123",
"contentType": "video/mp4",
"name": "セールスコール",
"description": "顧客との毎週のセールスコール",
"recorderName": "John Doe",
"recorderEmail": "john.doe@example.com"
}
}
レスポンス:
200
- ファイルのアップロードが正常にファイナライズされました400
- 無効なリクエストパラメータ403
- アップロード制限を超えました500
- サーバーエラー
マルチパートアップロード(大きなファイル用)
PUT /files/upload/multipart/init/{teamId}/{folderId}
大きなファイルのマルチパートアップロードを初期化
パスパラメータ:
teamId
- チームのIDfolderId
- フォルダのID
リクエストボディ:
{
"contentType": "video/mp4"
}
レスポンス:
200
- アップロードが正常に初期化されました400
- 無効なリクエストパラメータ500
- サーバーエラー
レスポンスの例:
{
"success": true,
"data": {
"fileId": "file789",
"uploadId": "upload123"
}
}
PUT /files/upload/multipart/url/{teamId}/{folderId}/{fileId}/{uploadId}/{partNumber}
特定のパートのアップロードURLを取得
パスパラメータ:
teamId
- チームのIDfolderId
- フォルダのIDfileId
- アップロードされるファイルのIDuploadId
- マルチパートアップロードセッションのIDpartNumber
- パート番号(1〜10000)
リクエストボディ:
{
"contentType": "video/mp4"
}
レスポンス:
200
- アップロードURLが正常に生成されました400
- 無効なリクエストパラメータ500
- サーバーエラー
レスポンスの例:
{
"success": true,
"data": {
"uploadUrl": "https://presigned-s3-url.com/part1"
}
}
PUT /files/upload/multipart/finalize/{teamId}/{folderId}/{fileId}/{uploadId}
マルチパートアップロードをファイナライズ
パスパラメータ:
teamId
- チームのIDfolderId
- フォルダのIDfileId
- アップロードされるファイルのIDuploadId
- マルチパートアップロードセッションのID
リクエストボディ:
{
"file": {
"contentType": "video/mp4",
"recorderName": "John Doe",
"recorderEmail": "john@example.com",
"name": "私の録音",
"description": "録画されたビデオセッション",
"notes": [
{
"text": "重要な点が議論されました",
"timestamp": 1234567890
}
]
}
}
レスポンス:
200
- アップロードが正常にファイナライズされました400
- 無効なリクエストパラメータ404
- アクティブなアップロードが見つかりません500
- サーバーエラー
PUT /files/upload/multipart/fallback/{teamId}/{folderId}/{fileId}/{partNumber}
バックエンド経由でファイルパートをアップロード(フォールバック)
パスパラメータ:
teamId
- チームのIDfolderId
- フォルダのIDfileId
- アップロードされるファイルのIDpartNumber
- パート番号(1〜10000)
フォームデータ:
file
- アップロードするファイルパートcontentType
- アップロードされるファイルのMIMEタイプ
レスポンス:
200
- パートが正常にアップロードされました400
- 無効なリクエストパラメータ500
- サーバーエラー
アカウント管理
POST /v2/account/tag
認証されたユーザーにタグを追加
リクエストボディ:
{
"key": "color",
"value": "red"
}
レスポンス:
200
- タグが正常に追加されました400
- 無効なリクエストパラメータ
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"
}
レスポンス:
200
- プロファイルが正常に更新されました400
- 無効なリクエストパラメータ
高度な機能
AI分析
AIを使用して録音を分析し、インサイトを得る:
// 録音のAI分析をリクエスト
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: "主な議論点は何ですか?",
mediaAnalysisOptions: {
transcript: {
segments: [{ start: 0, end: 300 }]
},
video: {
segments: [{ start: 0, end: 300 }]
}
}
})
});
バッチ処理
複数の録音を効率的に管理:
// 複数の録音にタグを付ける
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);
}
エラー処理
一般的なエラーコード
400
: 無効なリクエストパラメータ403
: AI使用制限を超えたか、不正なアクセス404
: リソースが見つかりません500
: サーバーエラー
エラーレスポンスの形式
エラーレスポンスは通常、次の形式に従います。
{
"success": false,
"message": "詳細なエラーメッセージ"
}
例
チームWebhookの設定
Webhookを使用すると、録音の処理時にリアルタイムで更新を受け取ることができます。
// チームの新しいwebhookを登録する
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();
}
// 使用例
const result = await registerTeamWebhook(
'team123',
'https://your-domain.com/webhooks/screenapp',
'録音の更新'
);
大きなファイルのアップロードと処理
100MBを超えるファイルの場合は、マルチパートアップロードフローを使用します。
// 1. アップロードを初期化
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. ファイルをチャンクに分割して、各パートをアップロード
const CHUNK_SIZE = 5 * 1024 * 1024; // 5MBチャンク
const totalParts = Math.ceil(file.size / CHUNK_SIZE);
for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
// このパートのアップロードURLを取得する
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();
// ファイルからチャンクを作成する
const start = (partNumber - 1) * CHUNK_SIZE;
const end = Math.min(start + CHUNK_SIZE, file.size);
const chunk = file.slice(start, end);
// チャンクをS3に直接アップロードする
await fetch(uploadUrl, {
method: 'PUT',
body: chunk,
headers: {
'Content-Type': 'video/mp4'
}
});
}
// 3. アップロードをファイナライズする
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: '顧客との会議の録音',
description: 'クライアントとの四半期レビュー',
recorderName: 'Jane Smith',
recorderEmail: 'jane@example.com'
}
})
}
);