Gemini Chat Completion API 申请及使用
内容提要
本文介绍Gemini Chat Completion API的申请与使用方法。需先在Ace Data Cloud控制台获取API Token，填写authorization、model和messages参数即可调用。支持多模态图片/视频输入、流式响应及多轮对话，并提供了Python、Java等代码示例及错误处理说明。
延伸解读
申请与鉴权要点
使用该 API 前需在 Ace Data Cloud 控制台获取 API Token，并在请求头 authorization 字段中以 Bearer 形式携带。一个 Token 可调用平台所有服务，首次申请有免费额度，额度不足时需在控制台充值。注意 401 错误表示 Token 无效或缺失，需检查 Token 是否正确。
多模态输入格式
图片和视频通过 content 数组中的 image_url 块传入，url 字段支持 base64 data URI 或公开 URL。注意不要使用 media_type 字段，那是 Anthropic Claude 的格式。支持的图片类型包括 png、jpeg、webp、heic、heif。视频输入同样通过 image_url 传递，但需确保 URL 可公开访问。
流式响应与思考模型
设置 stream 为 true 可启用流式响应，返回以 data: 开头的 JSON 行，以 [DONE] 结束。gemini-3.x flash 系列为思考模型，会先消耗 reasoning tokens，建议将 max_tokens 设为 512 以上，否则可能只返回空内容。流式响应中，choices 的 delta 字段包含增量内容，需自行拼接。
错误处理与限流
API 错误通过 HTTP 状态码和错误码返回，如 400 token_mismatched、401 invalid_token、429 too_many_requests、500 api_error。429 表示请求过于频繁，需注意限流。错误响应包含 trace_id，可用于排查问题。建议在代码中处理这些错误码，并实现重试或降级策略。
Q&A
如何申请Gemini Chat Completion API的Token？
需要先到Ace Data Cloud控制台获取API Token。如果尚未登录或注册，会自动跳转到登录页面，注册登录后会自动返回当前页面。一个API Token即可调用平台所有服务，首次申请会赠送免费额度。
调用Gemini Chat Completion API需要哪些必填参数？
至少需要填写三个参数：authorization（在控制台获取的API Token）、model（选择Gemini官网模型，如gemini-3.5-flash）、messages（提问词数组，包含role和content）。
Gemini Chat Completion API支持哪些多模态输入？如何传入图片？
支持图片和视频输入。传入图片时，将消息的content改为内容块数组，包含text块和image_url块。image_url.url支持base64 data URI（推荐）或公开可访问的图片URL。支持的图片类型有png、jpeg、webp、heic、heif。
如何启用Gemini Chat Completion API的流式响应？
在请求参数中将stream设置为true，API将逐行返回JSON数据，每行以data:开头，最后以data: [DONE]结束。代码层面需要相应修改以逐行读取响应。
如何实现多轮对话？
在messages字段中上传多个提问词，每个提问词包含role（user、assistant、system）和content。例如先传user的“Hello”，再传assistant的回复，最后传user的“What model are you?”，即可实现多轮对话。
Gemini 3.1 Pro与Gemini 3.0 Pro在多模态支持上有何区别？
Gemini 3.1 Pro是Gemini 3.0 Pro的升级版本，底层模型为gemini-3.1-pro-preview，同样支持文本、图像、视频等多模态输入，但具备更强的推理和理解能力。使用方式与3.0 Pro完全一致，只需将model参数替换为gemini-3.1-pro。
调用Gemini Chat Completion API时常见的错误代码有哪些？
常见错误代码包括：400 token_mismatched（参数缺失或无效）、400 api_not_implemented（参数缺失或无效）、401 invalid_token（授权token无效或缺失）、429 too_many_requests（请求频率超限）、500 api_error（服务器内部错误）。
