Skip to Content
GGPU API进阶能力

进阶能力索引

当基础文本、图片、模型与任务接口不能覆盖需求时,再从这里定位对应的扩展能力。

这些接口不是每个接入都需要,也不代表所有账号和模型默认开放。生产接入前,请确认能力已开通,并以目标接口的实际请求体和返回体为准。

先从稳定主路径开始

大多数应用应优先验证以下接口:

目标推荐接口
同步或流式文本对话POST /v1/chat/completions
图片生成POST /v1/images/generations
查询模型GET /v1/models
跟踪异步任务/v1/tasks 相关接口

只有当业务明确需要另一种请求协议、文件工作流、多模态向量或实时双向连接时,再进入扩展接口。

按能力查找接口

能力组能力方法路径适合解决什么问题
生成ResponsesPOST/v1/responses使用 Responses 形式组织生成请求
消息消息接口POST/v1/messages使用消息协议发起模型调用
消息Token 计数POST/v1/messages/count_tokens在正式调用前评估输入 Token
向量多模态 EmbeddingsPOST/embeddings/multimodal为多模态内容生成向量表示
文件文件列表GET/v1beta/files查找已上传文件
文件创建或初始化上传POST/v1beta/files开始文件上传流程
文件文件详情GET/v1beta/files/{file_id}查询单个文件状态与信息
文件文件删除DELETE/v1beta/files/{file_id}删除不再需要的文件
文件分片上传POST/upload/v1beta/files/sessions/{session_id}继续大文件或分片上传会话
实时WebSocketGET/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent建立实时双向生成连接

接入一项进阶能力

确认业务确实需要

先写清楚基础接口不能满足的具体要求,例如需要文件生命周期、调用前 Token 估算或实时双向连接。

确认账号与模型已开放

不要把“文档列出接口”等同于“当前账号一定可用”。先确认目标模型、权限和相关资源已具备。

从最小请求验证协议

只传必需字段,保存原始状态码和响应体。进阶接口之间的数据结构不同,不能直接复用 Chat Completions 的解析逻辑。

单独设计生命周期

文件、上传会话和 WebSocket 都包含额外状态。明确创建、使用、结束、失败与清理分别由谁处理。

再补生产保障

加入超时、重试边界、资源清理、日志脱敏、用量观察和异常告警,并用真实失败场景验证。

兼容性边界

不应假设应该怎么做
所有模型支持同一组进阶接口逐个验证目标模型与能力组合
不同接口共享完全相同的请求字段为每种协议建立独立类型与解析器
v1beta 路径与稳定接口一样长期不变封装调用层,并在升级前做回归验证
WebSocket 与普通 HTTP 有相同失败处理单独处理连接、消息、关闭与重连状态
上传完成后资源会自动按业务需求清理记录文件和会话 ID,明确清理策略

继续接入