1. 引言agora-api 是声网Agora官方提供的 Python 服务端 SDK 包用于在服务端生成临时 Token、管理频道、查询通话质量数据等。它面向开发者提供了一套简洁的接口帮助你在不依赖客户端的情况下完成鉴权、频道管理和数据统计等操作。本文将从功能、安装、语法参数、9 个实际应用案例以及常见错误与注意事项五个方面系统介绍 agora-api 包的使用方法。2. agora-api 包的核心功能agora-api 包主要提供以下几类能力Token 生成为音视频通话、实时消息等场景生成 RTC Token、RTM Token 和 Chat Token支持设置有效期和自定义权限。频道管理查询频道内用户列表、用户角色、频道状态等帮助服务端掌握实时通话情况。云端录制发起、查询和停止云端录制任务支持设置录制文件存储位置和录制模式。数据统计获取通话质量、用户行为等统计数据用于运营分析和问题排查。签名校验提供消息签名生成与校验能力保障服务端与客户端之间的通信安全。3. 安装与环境准备agora-api 包可以通过 pip 直接安装推荐在 Python 3.7 及以上版本中使用。pip install agora-api安装完成后可以通过以下方式验证是否安装成功import agora_api print(agora_api.__version__)使用前需要准备以下信息App ID在声网控制台创建项目后获取用于标识你的应用。App Certificate在控制台开启证书服务后获取用于生成 Token 时签名。Customer ID 和 Customer Secret用于调用 RESTful API 时进行身份认证。4. 基础语法与参数说明agora-api 包的核心用法是创建客户端对象然后调用对应方法完成操作。下面介绍最常用的几个接口。4.1 创建客户端from agora_api.client import AgoraClient client AgoraClient( app_idyour_app_id, app_certificateyour_app_certificate, customer_idyour_customer_id, customer_secretyour_customer_secret )参数说明app_id必填声网项目的 App ID。app_certificate开启证书服务后必填用于 Token 签名。customer_id调用 RESTful API 时必填用于身份认证。customer_secret与 customer_id 配套使用用于生成访问令牌。4.2 生成 RTC Tokentoken client.generate_rtc_token( channel_nametest_channel, uid12345, rolepublisher, expire_in_seconds3600 ) print(token)参数说明channel_name必填频道名称字符串类型。uid用户 ID整数类型用于标识加入频道的用户。role用户角色可选值为publisher主播或subscriber观众默认是publisher。expire_in_secondsToken 有效期单位为秒默认 3600 秒。4.3 查询频道用户列表users client.get_channel_users(channel_nametest_channel) print(users)该方法返回频道内当前在线用户的 UID 列表可用于服务端判断频道活跃状态。5. 9 个实际应用案例案例一生成 RTC Token 并返回给客户端这是最常见的场景。服务端在用户登录后生成 Token客户端携带 Token 加入频道。from agora_api.client import AgoraClient client AgoraClient( app_idyour_app_id, app_certificateyour_app_certificate ) def get_token(user_id, channel_name): token client.generate_rtc_token( channel_namechannel_name, uiduser_id, rolepublisher, expire_in_seconds7200 ) return token 调用示例 token get_token(1001, room_001) print(生成的 Token 为, token)案例二生成 RTM Token 用于实时消息实时消息场景需要单独的 RTM Token用于登录 RTM 系统。rtm_token client.generate_rtm_token( user_iduser_001, expire_in_seconds3600 ) print(RTM Token, rtm_token)这里user_id是字符串类型与 RTC Token 的 uid 不同需要注意区分。案例三批量生成多个频道的 Token当用户需要同时加入多个频道时可以循环调用生成方法。channels [room_a, room_b, room_c] tokens {} for ch in channels: tokens[ch] client.generate_rtc_token( channel_namech, uid1001, rolepublisher, expire_in_seconds3600 ) print(tokens)案例四查询频道在线用户列表在运营后台中经常需要查看某个频道当前有多少人在线。online_users client.get_channel_users(channel_nameroom_001) print(当前在线用户, online_users)案例五发起云端录制任务录制是教育、会议类应用的常见需求。下面演示如何发起录制。record_task client.start_recording( channel_nameroom_001, uid0, storage_config{ vendor: 1, region: 0, bucket: my-bucket, access_key: your_access_key, secret_key: your_secret_key } ) print(录制任务 ID, record_task)案例六查询录制任务状态status client.query_recording(task_idyour_task_id) print(录制状态, status)案例七停止录制任务result client.stop_recording(task_idyour_task_id) print(停止结果, result)案例八获取通话质量统计数据通过 RESTful API 可以获取指定时间段的通话质量数据用于问题排查。stats client.get_call_stats( start_time2026-09-01 00:00:00, end_time2026-09-01 23:59:59 ) print(stats)案例九生成消息签名用于服务端校验signature client.generate_signature( messagehello world, secretyour_secret ) print(签名, signature)6. 常见错误与使用注意事项6.1 常见错误App ID 或 App Certificate 错误会导致 Token 生成失败或生成的 Token 无法通过校验请检查控制台配置。Token 过期Token 有有效期过期后客户端无法加入频道需要重新生成。uid 类型错误RTC Token 的 uid 是整数RTM Token 的 user_id 是字符串混用会导致鉴权失败。网络超时调用 RESTful API 时可能因网络问题超时建议增加重试机制。权限不足未正确配置 customer_id 和 customer_secret 时调用管理类接口会返回权限错误。6.2 使用注意事项保护密钥App Certificate、customer_secret 等敏感信息不要硬编码在前端代码中应保存在服务端环境变量或配置中心。合理设置 Token 有效期有效期不宜过长建议根据业务场景设置为 1 到 24 小时。区分 Token 类型RTC、RTM、Chat 场景使用不同的 Token不要混用。关注版本更新声网会不定期更新 SDK建议关注官方文档和版本发布说明。错误处理建议对网络异常、参数错误等情况进行捕获并记录日志便于排查问题。7. 总结agora-api 包为 Python 开发者提供了便捷的声网服务端接入能力覆盖 Token 生成、频道管理、云端录制和数据统计等核心场景。通过本文介绍的 9 个案例你可以快速上手并集成到自己的业务中。在实际使用中注意保护好密钥、合理设置 Token 有效期并做好错误处理就能稳定地使用该包为你的音视频应用提供支撑。《AI提示工程必知必会》主要内容包括各类提示词的应用如问答式、指令式、状态类、建议式、安全类和感谢类提示词以及如何通过实战演练掌握提示词的使用技巧使用提示词进行文本摘要、改写重述、语法纠错、机器翻译等语言处理任务以及在数据挖掘、程序开发等领域的应用AI在绘画创作上的应用百度文心一言和阿里通义大模型这两大智能平台的特性与功能以及市场调研中提示词的实战应用。通过阅读《AI提示工程必知必会》读者可掌握如何有效利用AI提示工程提升工作效率创新工作流程并在职场中脱颖而出。
