API

相关源文件

• etc/tool/commit.py
• etc/unittest/models.py
• g4f/Provider/Cloudflare.py
• g4f/Provider/Copilot.py
• g4f/Provider/har/__init__.py
• g4f/Provider/hf_space/Qwen_Qwen_3.py
• g4f/Provider/hf_space/__init__.py
• g4f/api/__init__.py
• g4f/client/__init__.py
• g4f/client/stubs.py
• g4f/providers/any_provider.py

本文档涵盖了 g4f 系统提供的 REST API 接口，包括 FastAPI 服务器端点、客户端库和身份验证机制。该 API 提供与 OpenAI 兼容的聊天补全、图像生成和其他 AI 操作的端点，同时抽象了对多个底层提供商的访问。

有关详细的端点规范，请参阅 FastAPI Endpoints。有关 GUI 使用的内部后端 API，请参阅 Backend API。有关客户端库的使用，请参阅 Synchronous Client 和 Asynchronous Client。

API 架构概述

g4f API 系统通过统一的抽象层提供了多种访问 AI 提供商的接口。

来源： g4f/api/__init__.py72-103 g4f/client/__init__.py326-340 g4f/client/__init__.py617-632

主要 API 组件

FastAPI 应用工厂

API 使用工厂模式创建不同配置的 FastAPI 应用。

功能	目的	配置
create_app()	标准 API 服务器	基本的 FastAPI，支持 CORS
create_app_debug()	开发服务器	启用了调试
create_app_with_gui_and_debug()	功能齐全的服务器	GUI + 调试
create_app_with_demo_and_debug()	演示服务器	GUI + 演示模式 + 调试

工厂函数在需要时配置 AppConfig 类并挂载 Flask GUI 应用。

来源： g4f/api/__init__.py72-118

API 类结构

Api 类是管理所有 API 操作的中心类。

主要职责

• 通过 register_routes() 注册路由
• 通过 register_authorization() 进行身份验证中间件
• 通过 register_validation_exception_handler() 进行请求验证
• 为有状态提供商管理会话状态

来源： g4f/api/__init__.py152-158 g4f/api/__init__.py224-807

客户端库类

Python 客户端库同时提供同步和异步接口。

类	类型	目的
客户端	同步	同步 API 访问
AsyncClient	异步	异步 API 访问
自动补全	两者	聊天补全操作
图像	两者	图像生成操作
对话	容器	分组补全操作

来源： g4f/client/__init__.py326-340 g4f/client/__init__.py617-632 g4f/client/__init__.py341-411

认证系统

多层身份验证

API 支持多种身份验证机制。

来源： g4f/api/__init__.py176-206 g4f/api/__init__.py162-174

基于路径的授权

身份验证中间件根据请求路径应用不同的规则。

路径模式	需要身份验证	特殊规则
/v1/*	始终	g4f-api-key 或 Bearer token
/api/*	始终	提供商特定端点
/backend-api/*	有条件	演示模式或 Basic auth
/images/*, /media/*	从不	公共静态资产
/chat/*	有条件	非根路径的 Basic auth

来源： g4f/api/__init__.py189-205

请求/响应流程

聊天补全请求流程

来源： g4f/api/__init__.py312-397 g4f/client/__init__.py644-695

响应流式实现

对于流式响应，API 使用 Server-Sent Events。

来源： g4f/api/__init__.py370-385

配置系统

AppConfig 类

AppConfig 类提供全局配置管理。

设置	类型	目的
ignored_providers	list[str]	要排除的提供商
g4f_api_key	str	全局 API 密钥
ignore_cookie_files	bool	跳过 HAR 文件加载
model	str	默认模型覆盖
provider	str	默认提供商覆盖
media_provider	str	默认媒体提供商
proxy	str	代理配置
gui	bool	启用 Web GUI
demo	bool	启用演示模式

可以通过 AppConfig.set_config(**data) 以编程方式设置配置。

来源： g4f/api/__init__.py136-151

请求配置模型

API 使用 Pydantic 模型进行请求验证。

• ChatCompletionsConfig - 聊天补全参数
• ImageGenerationConfig - 图像生成参数
• AudioSpeechConfig - 音频合成参数
• ResponsesConfig - 通用响应参数

这些模型处理参数验证、默认值和类型转换。

来源： g4f/api/stubs.py1-318

集成点

提供商集成

API 通过几个关键接口与提供商系统集成。

集成点	目的	实现
convert_to_provider()	提供商名称解析	字符串到提供商类的映射
AnyProvider	自动提供商选择	多提供商回退逻辑
AsyncClient	核心引擎访问	统一异步接口
HAR 文件身份验证	提供商会话管理	提取的浏览器会话

来源： g4f/client/service.py g4f/providers/any_provider.py38-267 g4f/api/__init__.py351-365

错误处理集成

API 为所有端点提供了一致的错误处理。

这会创建包含提供商和模型信息的统一 JSON 错误响应。

来源： g4f/api/__init__.py787-806