PHASEO_API_KEY。
安装列出了每种语言的安装命令和要求。C++ SDK 尚未发布。
你发送什么,拿回什么
在每个 SDK 中,请求正文都使用 API 的 JSON 字段名。用法为每个端点提供了一个示例。
缺少密钥时,创建客户端就会失败。Python 抛出
ValueError,Go 的 NewFromEnv() 返回错误,C# 和 PHP 抛出 Missing API key. Pass apiKey or set PHASEO_API_KEY.,Ruby 抛出 ArgumentError: Missing API key. Pass api_key or set PHASEO_API_KEY.,Rust 的 Phaseo::from_env() 返回 PhaseoError。
找到每个端点对应的方法
短横线表示该 SDK 没有针对此操作的封装。请使用最后一行中的方法,或直接调用 HTTP API。“仅 JSON”表示该方法无法发送 multipart 文件上传:请改为传入 URL 或 base64 data URL,或者像端点页面所示,用你所用语言的 HTTP 客户端发送上传。大多数 SDK 还为每个generate… 方法提供了 create… 别名(例如 Go 和 C# 中的 CreateChatCompletion,Ruby 中的 create_response)。
C#、PHP、Ruby 和 Java 有上传方法,但它发送的是 JSON,无法上传文件;文件和 STT 展示了每种语言的 multipart 请求。除 Rust 外,每个 SDK 的密钥和工作区还提供
get、update 和 delete 方法,以及当前密钥查询(getCurrentApiKey、get_current_api_key、GetCurrentApiKey)。TypeScript 和 Python 还覆盖音乐、OCR、解析、决策和提取。
查看每个包包含的内容
已发布的包早于 SDK 源码中的部分功能:配置客户端
- TypeScript
- Python
- Go
- C#
- PHP
- Ruby
- Java
- Rust
等待音乐、视频或批处理完成
等待辅助方法仅在 TypeScript 和 Python 中提供。其他 SDK 从创建调用中返回任务;请用 get 方法轮询它,或打开它的任务 WebSocket URL。videos.generateAndWait / videos.generate_and_wait,批处理使用 batches.createAndWait / batches.create_and_wait。每个辅助方法只提交一次。如果第一个响应已经完成,它会直接返回而不轮询;否则它会轮询同一个任务直到结束,并返回完整响应。失败、取消或过期的任务会抛出 JobFailedError,其 response 包含详细信息。已完成的批处理中仍可能包含失败的单个请求。
每个资源上的 wait(id, options) 会接续一个已有任务,并返回任何终态响应,包括失败。在 Python 中,音乐还提供 create(request) 和 retrieve(id)。
JobTimeoutError 和 JobCancelledError 会保留任务 ID 和最后一个响应(TypeScript 中为 jobId/lastResponse,Python 中为 job_id/last_response),因此你可以用 .wait(error.jobId) 或 .wait(error.job_id) 接续。停止等待不会取消远程任务。在 TypeScript 中,它会取消正在进行的轮询;同步 Python 客户端在请求和回调之间检查取消和截止时间,因此无法中断已经在进行的 HTTP 调用。HTTP 失败会原样抛出,提交永远不会重试。这些辅助方法从你的进程中轮询;它们不会给网关增加后台执行。
跨进程保留句柄
music.start、videos.start 和 batches.start 返回一个带有 result()、events() 和 cancel() 的句柄,以及 toJSON()(TypeScript)或 to_dict()(Python)。保存它返回的类型和 ID,之后用 resume(id) 重建句柄。result() 遇到终态失败时会抛出异常。只有视频和批处理任务支持 cancel()。在 AsyncPhaseo 上,请 await 这些方法,并用 async for 迭代事件。
请求控制和错误
在 TypeScript、Python 和 Java 中,重试默认为0,并且只适用于 GET 和 HEAD 请求。付费提交、写入和流式请求永远不会重试。
- TypeScript
- Python
- Java
- Rust
withOptions(...) 返回一个新客户端,这些控制会应用到它的每个资源、流和媒体调用;原客户端保持不变。重试遵循 Retry-After。timeoutMs 包括读取响应正文的时间。responseMetadata(result) 返回网关请求 ID 和控制台追踪 URL。HTTP 错误为 PhaseoHttpError,包含 HTTP status、API 错误 code、requestId、traceUrl、重试延迟、正文和 headers。调用没有封装的端点
每个 SDK 还附带由 Phaseo OpenAPI 规范生成的客户端:
生成的操作比封装方法更底层;有封装方法时请优先使用封装方法。
解析输出并收集流
这些辅助方法仅在 TypeScript 和 Python 中提供。responses.parse(request, schema) 验证已完成的 JSON 响应。在 TypeScript 中,schema 是兼容 Zod 的解析器;在 Python 中,是一个 Pydantic 模型。同时还要在请求中设置结构化输出格式;解析器只负责验证。
collectStream(client.streamResponses(request))(TypeScript),或 collect_stream 和 collect_async_stream(Python),会汇总流式输出的文本和用量。
调用前检查模型
checkModelCapabilities / check_model_capabilities(TypeScript 和 Python)会针对一个活跃的提供商报价,检查其公布的能力和标量约束(inputTypes、outputTypes、endpoints、parameters、parameterValues,Python 中为对应的 snake_case 名称)。它从不更换模型或丢弃参数,也无法保证实时提供商一定会接受请求。缺少元数据时处理方式不同:TypeScript 将其报告为未知,Python 则判定检查失败。
对于模型选择器和参数编辑器,请使用实时端点元数据:
supported、partial、unsupported 或 unknown,并附带匹配的提供商路由和约束问题,你可以在界面中就地高亮显示。这些检查需要显式调用;它们不会给生成请求增加查询。模型列出了每个 SDK 中的对应方法。
不联网进行测试
- TypeScript
- Python
从
@phaseo/sdk/testing 导入 createMockTransport 和 jobFixtures,并把 mock 的 fetchImpl 传给客户端。fixture 是严格且有序的:意外的调用会在本地失败,永远不会到达网络。调用 mock.assertDone() 检查每个预期请求是否都已发生。从房间导出代码
在 Phaseo 房间中发送请求后,获取代码 会将其模型和设置导出为 TypeScript 或 Python,并且在有请求 ID 时,查看请求 会打开它的控制台追踪。请在设置了PHASEO_API_KEY 的服务器上运行导出的代码。