Back to Details

paxs-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PAXS AI Platform Integration

PAXS AI平台集成

You help users connect to and use the PAXS AI platform for transcription, meeting notes, and meeting management.
您可以帮助用户连接并使用PAXS AI平台进行转录、会议纪要生成和会议管理。

Authentication

认证

PAXS uses OAuth2 with Google login. Before calling any API, check if the user has a valid access token.
PAXS采用基于Google登录的OAuth2认证方式。在调用任何API之前，请检查用户是否拥有有效的访问令牌。

If No Token Exists

无可用令牌时

  1. Generate a state parameter: a random string for CSRF protection
  2. Present the user with an authorization link:
https://dzd.paxs.ai/api/oauth/provider/authorize?redirect_uri={CALLBACK_URL}&response_type=code&state={STATE}
  1. After the user clicks and authorizes, they will be redirected to the callback URL with 
    ?code=xxx&state=xxx
  2. Exchange the code for tokens:
POST https://dzd.paxs.ai/api/oauth/provider/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<CODE>",
  "redirect_uri": "<CALLBACK_URL>"
}
Response:
json
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "session media analysis user:read"
}
  1. Store the tokens in 
    .claude/skills/paxs-api/.tokens.json
    :
json
{
  "access_token": "...",
  "refresh_token": "..."
}
  1. 生成state参数：一个用于CSRF保护的随机字符串
  2. 向用户展示授权链接：
https://dzd.paxs.ai/api/oauth/provider/authorize?redirect_uri={CALLBACK_URL}&response_type=code&state={STATE}
  1. 用户点击并授权后，将被重定向至回调URL，携带参数
    ?code=xxx&state=xxx
  2. 用授权码换取令牌：
POST https://dzd.paxs.ai/api/oauth/provider/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<CODE>",
  "redirect_uri": "<CALLBACK_URL>"
}
响应：
json
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "session media analysis user:read"
}
  1. 将令牌存储在
    .claude/skills/paxs-api/.tokens.json
    中：
json
{
  "access_token": "...",
  "refresh_token": "..."
}

Token Storage

令牌存储

  • Tokens are stored at 
    .claude/skills/paxs-api/.tokens.json
  • Always read tokens from this file before making API calls
  • After obtaining or refreshing tokens, update this file immediately
  • 令牌存储在
    .claude/skills/paxs-api/.tokens.json
    中
  • 调用API前务必从此文件读取令牌
  • 获取或刷新令牌后，立即更新此文件

If Token Expired (401 Response)

令牌过期时（返回401响应）

Refresh the token:
POST https://dzd.paxs.ai/api/oauth/provider/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "<REFRESH_TOKEN>"
}
The response returns new access_token and refresh_token. Always store the latest tokens.
刷新令牌：
POST https://dzd.paxs.ai/api/oauth/provider/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "<REFRESH_TOKEN>"
}
响应将返回新的access_token和refresh_token。请始终存储最新的令牌。

Token Lifetime

令牌有效期

  • Access token: 1 hour
  • Refresh token: 30 days
  • 访问令牌：1小时
  • 刷新令牌：30天

Supported File Formats

支持的文件格式

Audio: MP3, WAV, FLAC, MPA, AAC, Opus, M4A Video: MPEG, MP4, FLV, WebM, WMV, 3GP
Before uploading, validate the file extension. Reject unsupported formats with a clear error message listing the accepted formats above.
音频： MP3, WAV, FLAC, MPA, AAC, Opus, M4A 视频： MPEG, MP4, FLV, WebM, WMV, 3GP
上传前请验证文件扩展名。若格式不支持，需清晰告知用户并列出上述支持的格式。

API Reference

API参考

All API calls require the header: 
Authorization: Bearer <ACCESS_TOKEN>
Base URL: 
https://dzd.paxs.ai
(hardcoded for local development)
所有API调用均需携带请求头：
Authorization: Bearer <ACCESS_TOKEN>
基础URL：
https://dzd.paxs.ai
（本地开发时为硬编码）

Get Current User

获取当前用户信息

GET /api/users/me
Use this to verify the token works and get the user's profile.
GET /api/users/me
用于验证令牌有效性并获取用户资料。

Create a Meeting

创建会议

POST /api/sessions
Content-Type: application/json

{
  "title": "Meeting title",
  "description": "Optional description",
  "attendees": [
    {"email": "user@example.com", "displayName": "User Name", "role": "participant", "source": "manual"},
    {"email": "other@example.com", "displayName": "Other Person", "role": "participant", "source": "manual"}
  ]
}
Attendee fields:
FieldTypeRequiredDefaultDescription
email
stringYes—Attendee email (cannot be empty)
displayName
stringYes—Attendee display name (cannot be empty)
role
stringNo
"Unknown"
Attendee role
source
stringNo
"manual"
Source: 
"manual"
, 
"event"
, or 
"zoom_participant"
Important: 
attendees
is required when creating a meeting. The user must provide at least the attendee list. If the user does not provide attendees, ask them before proceeding.
Returns the created meeting with an 
id
.
POST /api/sessions
Content-Type: application/json

{
  "title": "Meeting title",
  "description": "Optional description",
  "attendees": [
    {"email": "user@example.com", "displayName": "User Name", "role": "participant", "source": "manual"},
    {"email": "other@example.com", "displayName": "Other Person", "role": "participant", "source": "manual"}
  ]
}
参会者字段说明：
字段类型是否必填默认值描述
email
字符串是—参会者邮箱（不能为空）
displayName
字符串是—参会者显示名称（不能为空）
role
字符串否
"Unknown"
参会者角色
source
字符串否
"manual"
来源：
"manual"
、
"event"
或
"zoom_participant"
重要提示： 创建会议时必须提供
attendees
参数。用户至少需提供参会者列表。若用户未提供，需先询问用户。
返回已创建的会议及其
id
。

Upload a Recording

上传录制文件

POST /api/recordings?session_id={SESSION_ID}
Content-Type: multipart/form-data

file: <audio/video file>
Returns the attachment with an 
id
.
Important: The 
session_id
must be sent as a form field (not a query parameter).
Constraints:
  • One recording per meeting — Each meeting can only have one active recording. Uploading a new recording replaces the existing one.
  • Auto-pipeline — After a successful upload, the backend automatically triggers the full analysis pipeline: transcription first, then meeting note upon transcription completion. No manual analysis request is needed.
  • MIME type required — When uploading via curl, specify the correct MIME type (e.g., 
    file=@recording.wav;type=audio/wav
    ). Without it, the server rejects the file.
  • If the user provides multiple audio files, create a separate meeting for each file.
POST /api/recordings?session_id={SESSION_ID}
Content-Type: multipart/form-data

file: <audio/video file>
返回附件及其
id
。
重要提示： 
session_id
必须作为表单字段发送（而非查询参数）。
约束条件：
  • 每个会议仅支持一个录制文件 — 每个会议只能有一个有效录制文件。上传新文件将替换现有文件。
  • 自动流水线 — 上传成功后，后端将自动触发完整分析流程：先转录，转录完成后生成会议纪要。无需手动发起分析请求。
  • 需指定MIME类型 — 使用curl上传时，需指定正确的MIME类型（例如
    file=@recording.wav;type=audio/wav
    ）。若未指定，服务器将拒绝接收文件。
  • 若用户提供多个音频文件，需为每个文件创建单独的会议。

Request Analysis

请求分析

POST /api/analysis/request
Content-Type: application/json

{
  "session_id": "<SESSION_ID>",
  "attachment_id": "<ATTACHMENT_ID>",
  "analysis_types": ["transcription", "meeting note"],
  "instruction": "Generate a detailed meeting summary",
  "meeting_type": "group"
}
Available analysis types:
  • transcription
    — Speech-to-text
  • meeting note
    — Meeting summary (requires 
    instruction
    )
  • key_points
    — Extract key discussion points
  • sentiment
    — Sentiment analysis
Meeting types: 
group
, 
team
, 
department
, 
cross_functional
, 
organization
, 
company
Note: If requesting 
meeting note
, the 
instruction
field is required.
Dependency handling: The backend automatically resolves dependencies between analysis types. For example, passing 
["transcription", "meeting note"]
in a single request will automatically complete transcription first, then generate the meeting note. No need to make separate requests or wait between them.
POST /api/analysis/request
Content-Type: application/json

{
  "session_id": "<SESSION_ID>",
   "attachment_id": "<ATTACHMENT_ID>",
   "analysis_types": ["transcription", "meeting note"],
   "instruction": "Generate a detailed meeting summary",
   "meeting_type": "group"
}
支持的分析类型：
  • transcription
    — 语音转文字
  • meeting note
    — 会议纪要（需提供
    instruction
    参数）
  • key_points
    — 提取关键讨论要点
  • sentiment
    — 情感分析
会议类型：
group
、
team
、
department
、
cross_functional
、
organization
、
company
注意：若请求
meeting note
，则
instruction
字段为必填项。
依赖处理：后端会自动处理分析类型之间的依赖关系。例如，若传入
["transcription", "meeting note"]
，系统会自动先完成转录，再生成会议纪要。无需分开请求或等待。

Get Recording Analysis

获取录制文件分析结果

GET /api/recordings/{RECORDING_ID}/analysis?session_id={SESSION_ID}
Returns all analysis reports for a recording. Each report has a 
status
field:
  • pending
    — Not yet started
  • processing
    — In progress
  • completed
    — Done, results available
  • failed
    — Analysis failed
Optional query parameters:
  • analysis_type
    — Filter by specific type (e.g., 
    transcription
    , 
    meeting note
    )
GET /api/recordings/{RECORDING_ID}/analysis?session_id={SESSION_ID}
返回录制文件的所有分析报告。每个报告包含
status
字段：
  • pending
    — 尚未开始
  • processing
    — 处理中
  • completed
    — 已完成，结果可用
  • failed
    — 分析失败
可选查询参数：
  • analysis_type
    — 按特定类型筛选（例如
    transcription
    、
    meeting note
    ）

Polling Strategy

轮询策略

Analysis is asynchronous. After uploading a recording, poll this endpoint:
  1. Wait 5 seconds before the first poll
  2. Poll every 5 seconds: 
    GET /api/recordings/{RECORDING_ID}/analysis?session_id={SESSION_ID}
  3. Check the 
    status
    of each analysis type in the response
  4. Stop when transcription status is 
    completed
    or 
    failed
  5. Timeout after 5 minutes (60 polls)
分析为异步流程。上传录制文件后，需轮询此端点：
  1. 首次轮询前等待5秒
  2. 每5秒轮询一次：
    GET /api/recordings/{RECORDING_ID}/analysis?session_id={SESSION_ID}
  3. 检查响应中各分析类型的
    status
  4. 当转录状态为
    completed
    或
    failed
    时停止轮询
  5. 超时时间为5分钟（共60次轮询）

List meeting

列出会议

GET /api/sessions?page=1&page_size=20
GET /api/sessions?page=1&page_size=20

Get meeting Details

获取会议详情

GET /api/sessions/{SESSION_ID}
GET /api/sessions/{SESSION_ID}

One-Shot Mode

单次处理模式

When a user provides audio file(s), automatically handle the entire pipeline. The user must provide:
  • Audio file(s) — local path or URL
  • Attendees — list of participants with at least 
    email
    and 
    displayName
If attendees are not provided, ask the user before proceeding.
当用户提供音频文件时，自动处理完整流程。用户需提供：
  • 音频文件 — 本地路径或URL
  • 参会者 — 包含至少
    email
    和
    displayName
    的参会者列表
若未提供参会者，需先询问用户。

Single File

单个文件

  1. Validate file format (must be a supported audio/video format)
  2. Load tokens from 
    .claude/skills/paxs-api/.tokens.json
    (run OAuth if missing)
  3. Create a meeting with the filename as title and the provided attendees
  4. Upload the recording (backend auto-triggers transcription → meeting note pipeline)
  5. Poll analysis status every 5 seconds via 
    GET /api/recordings/{RECORDING_ID}/analysis?session_id={SESSION_ID}
  6. If transcription fails, retry upload up to 3 times. After 3 failures, notify the user.
  7. Once completed, return the results to the user
  1. 验证文件格式（必须为支持的音频/视频格式）
  2. 从
    .claude/skills/paxs-api/.tokens.json
    加载令牌（若缺失则执行OAuth流程）
  3. 以文件名作为标题，结合提供的参会者创建会议
  4. 上传录制文件（后端自动触发转录→会议纪要流程）
  5. 每5秒通过
    GET /api/recordings/{RECORDING_ID}/analysis?session_id={SESSION_ID}
    轮询分析状态
  6. 若转录失败，最多重试上传3次。3次失败后通知用户。
  7. 完成后将结果返回给用户

Multiple Files

多个文件

Each file gets its own meeting (one recording per meeting). Process sequentially:
  1. Validate all file formats first — reject any unsupported files before starting
  2. For each file, repeat the single file flow (steps 2-7)
  3. Present results grouped by file
每个文件对应一个独立会议（每个会议一个录制文件）。按顺序处理：
  1. 先验证所有文件格式 — 开始处理前拒绝任何不支持的文件
  2. 对每个文件重复单个文件的处理流程（步骤2-7）
  3. 按文件分组展示结果

Workflow

工作流程

When a user wants to transcribe or analyze a meeting recording:
  1. Load tokens — Read 
    .claude/skills/paxs-api/.tokens.json
    for stored credentials
  2. Authenticate — If no tokens, run the OAuth flow via 
    oauth_callback_server.py
    ; if token expired (401), refresh it
  3. Collect inputs — Ensure the user has provided: audio file + attendees list (ask if missing)
  4. Validate file — Check the file extension is a supported format before proceeding
  5. Create meeting — 
    POST /api/sessions
    with title and attendees (attendees required)
  6. Upload recording — 
    POST /api/recordings
    with the audio file as multipart form data (include 
    session_id
    as form field and correct MIME type)
  7. Monitor — The backend auto-triggers: transcription → meeting note. Poll via 
    GET /api/recordings/{RECORDING_ID}/analysis?session_id={SESSION_ID}
    every 5 seconds.
  8. Retry on failure — If transcription fails, retry the upload (max 3 attempts). After 3 failures, notify the user with the error details.
当用户需要转录或分析会议录制文件时：
  1. 加载令牌 — 读取
    .claude/skills/paxs-api/.tokens.json
    中的存储凭证
  2. 认证 — 若无令牌，通过
    oauth_callback_server.py
    执行OAuth流程；若令牌过期（返回401），则刷新令牌
  3. 收集输入 — 确保用户已提供：音频文件+参会者列表（若缺失则询问）
  4. 验证文件 — 继续前检查文件扩展名是否为支持的格式
  5. 创建会议 — 调用
    POST /api/sessions
    接口，传入标题和参会者（参会者为必填项）
  6. 上传录制文件 — 调用
    POST /api/recordings
    接口，以multipart表单数据形式上传音频文件（需将
    session_id
    作为表单字段，并指定正确的MIME类型）
  7. 监控状态 — 后端自动触发：转录→会议纪要流程。每5秒通过
    GET /api/recordings/{RECORDING_ID}/analysis?session_id={SESSION_ID}
    轮询状态
  8. 失败重试 — 若转录失败，最多重试上传3次后向用户通知错误详情。

Error Handling

错误处理

  • 401 Unauthorized
    → Token expired, refresh it
  • 403 Forbidden
    → Insufficient scope or permissions
  • 400 Bad Request
    → Check request parameters
  • 404 Not Found
    → Resource does not exist
  • 401 Unauthorized
    → 令牌过期，需刷新令牌
  • 403 Forbidden
    → 权限或作用域不足
  • 400 Bad Request
    → 检查请求参数
  • 404 Not Found
    → 资源不存在

Guidelines

注意事项

  • Always read tokens from 
    .claude/skills/paxs-api/.tokens.json
    before making API calls
  • When the token expires (401), automatically refresh, update 
    .tokens.json
    , and retry
  • Present the authorization link clearly and explain what it does
  • Always require attendees when creating a meeting — ask the user if not provided
  • After uploading a recording, the backend handles the full pipeline automatically (transcription → meeting note)
  • Do not manually call 
    /api/analysis/request
    in the standard flow — only use it for on-demand analysis types like 
    key_points
    or 
    sentiment
  • Poll every 5 seconds until completed (max 5 minutes)
  • On transcription failure, retry upload up to 3 times before notifying the user
  • When uploading via curl, always include the correct MIME type for the file
  • 调用API前务必从
    .claude/skills/paxs-api/.tokens.json
    读取令牌
  • 令牌过期时（返回401），自动刷新令牌、更新
    .tokens.json
    并重试请求
  • 清晰展示授权链接并说明其用途
  • 创建会议时必须要求用户提供参会者列表 — 若缺失需询问用户
  • 上传录制文件后，后端将自动处理完整流程（转录→会议纪要）
  • 标准流程中请勿手动调用
    /api/analysis/request
    接口 — 仅需在按需分析
    key_points
    或
    sentiment
    等类型时使用
  • 每5秒轮询一次状态，直至完成（最长等待5分钟）
  • 转录失败时，最多重试上传3次后通知用户
  • 使用curl上传时，务必为文件指定正确的MIME类型