SimLens API 文件

SimLens REST API 讓您能夠以程式化方式存取 AI 觀眾模擬功能，將 SimLens 的分析能力整合至您的應用程式或自動化工作流程。

⚠️ API 存取需要 Pro 或 Enterprise 方案。查看方案 →

驗證

所有 API 請求需要在 HTTP Header 中附上您的 API Key：

HTTP Header

Authorization: Bearer sl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

💡 前往 API 管理頁面建立您的 API Key。

Base URL

https://api.simlens.io/api/v1

錯誤處理

API 使用標準 HTTP 狀態碼，錯誤回應格式如下：

Error Response

{
  "detail": "錯誤說明訊息"
}

狀態碼	說明
`200`	請求成功
`201`	資源建立成功
`400`	請求格式錯誤
`401`	未授權 — 缺少或無效的 API Key
`403`	禁止存取 — 方案限制或權限不足
`404`	資源不存在
`429`	超過速率限制
`500`	伺服器內部錯誤

影片 API

管理影片資源

GET/videos列出影片

取得目前帳號的所有影片列表。

Response

{
  "items": [
    {
      "id": "uuid",
      "title": "影片標題",
      "status": "ready",  // processing | ready | error
      "duration": 120.5,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

POST/videos/upload上傳影片

使用 multipart/form-data 上傳影片檔案。

Request

Content-Type: multipart/form-data

file: <video_file>    # required
title: "影片標題"      # optional

Example (cURL)

curl -X POST https://api.simlens.io/api/v1/videos/upload \
  -H "Authorization: Bearer sl_live_xxxx" \
  -F "file=@video.mp4" \
  -F "title=我的影片"

分析報告 API

建立 AI 分析並取得報告

POST/reports建立分析報告

對指定影片與觀眾設定進行 AI 分析，回傳報告 ID。

Request Body

{
  "video_id": "uuid",      // required
  "audience_id": "uuid",   // required
  "title": "報告標題",      // optional
  "scenario": "分析情境說明" // optional
}

Response

{
  "id": "uuid",
  "title": "報告標題",
  "status": "processing",  // processing | completed | failed
  "created_at": "2025-01-01T00:00:00Z"
}

Example (Python)

import requests

API_KEY = "sl_live_your_key_here"
BASE_URL = "https://api.simlens.io/api/v1"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Create analysis
resp = requests.post(
    f"{BASE_URL}/reports",
    headers=headers,
    json={
        "video_id": "your-video-id",
        "audience_id": "your-audience-id",
        "title": "Q1 影片分析"
    }
)
report = resp.json()
print(f"Report ID: {report['id']}")

GET/reports/{"{id}"}取得報告

取得指定報告的完整分析結果。

{
  "id": "uuid",
  "title": "報告標題",
  "status": "completed",
  "retention_data": [...],
  "emotion_data": [...],
  "summary": "AI 分析摘要",
  "suggestions": [...],
  "created_at": "2025-01-01T00:00:00Z"
}

觀眾 API

管理觀眾設定

GET/audiences列出觀眾設定

取得目前帳號建立的所有觀眾設定，以及官方範本。

GET /audiences
GET /audiences/templates  # 官方範本

速率限制

方案	每月 API 呼叫	每秒限制
Free	不支援 API	-
Pro	1,000 次	10 req/s
Enterprise	無限制	100 req/s

SDK & 整合

官方 SDK 開發中，目前可直接使用 REST API 搭配您喜好的 HTTP 客戶端。

🐍

Python

pip install requests
# 使用 requests 直接呼叫

📦

Node.js

npm install axios
// 使用 axios 直接呼叫