# hanaokayuzu/gemini-api architecture

> Architecture diagram of the GitHub repository hanaokayuzu/gemini-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hanaokayuzu/gemini-api
- Repository: https://github.com/hanaokayuzu/gemini-api

## Overview

Gemini-API is an asynchronous Python wrapper around the Gemini web app, with a CLI as an alternate entry point. The primary workflow authenticates a client, sends prompts or files to Gemini, and returns structured or streamed outputs; chat history and Deep Research add distinct conversation and plan/poll/report stages. The README also documents Gems, extensions, and generated media. Sampled source confirms authentication, chat/history, research, parsing, and media behavior; several feature implementations are represented only by their documented enclosing directory, so their internal wiring is omitted.

Main entry points: [`src/gemini_webapi/client.py`](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/client.py) (Gemini client), [`src/gemini_webapi/components/research_mixin.py`](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/components/research_mixin.py) (Deep Research), [`src/gemini_webapi/utils/get_access_token.py`](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/utils/get_access_token.py) (Authentication), [`src/gemini_webapi/components/chat_mixin.py`](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/components/chat_mixin.py) (Chat and history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["Command line<br/>[cli.py]"]
end

subgraph group_session["Session and transport"]
  node_client["Gemini client<br/>[client.py]"]
  node_auth["Authentication"]
  node_browser_cookies["Browser cookies"]
  node_gemini{{"Gemini web app"}}
end

subgraph group_features["Gemini capabilities"]
  node_chat["Chat and history<br/>[chat_mixin.py]"]
  node_gems["Gems management<br/>[gem_mixin.py]"]
  node_research["Deep Research<br/>[research_mixin.py]"]
  node_extensions["Extensions"]
  node_generation["Media generation"]
  node_file_upload["File upload<br/>[upload_file.py]"]
end

subgraph group_data["Parsing and outputs"]
  node_response_parser["Response parsing<br/>[parsing.py]"]
  node_research_parser["Research extraction<br/>[research.py]"]
  node_outputs["Typed outputs"]
  node_media_download["Media downloads<br/>[video.py]"]
end

node_developer(("API user"))

node_developer -->|"calls"| node_client
node_developer -->|"runs"| node_cli
node_cli -->|"commands"| node_client
node_client -->|"authenticates"| node_auth
node_auth -.->|"loads optionally"| node_browser_cookies
node_auth -->|"requests session"| node_gemini
node_client -->|"sends requests"| node_gemini
node_gemini -->|"returns frames"| node_client
node_client -->|"uploads files"| node_file_upload
node_client -->|"parses responses"| node_response_parser
node_response_parser -->|"builds outputs"| node_outputs
node_client -->|"provides chat"| node_chat
node_chat -->|"uses transport"| node_client
node_client -->|"provides gem API"| node_gems
node_client -->|"provides research API"| node_research
node_research -->|"sends turns"| node_chat
node_research -->|"extracts reports"| node_research_parser
node_research -->|"returns plan and result"| node_outputs
node_client -->|"supports generation"| node_extensions
node_client -->|"supports generation"| node_generation
node_outputs -->|"saves generated media"| node_media_download

click node_cli "https://github.com/hanaokayuzu/gemini-api/blob/master/cli.py"
click node_client "https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/client.py"
click node_auth "https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/utils/get_access_token.py"
click node_browser_cookies "https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/utils/load_browser_cookies.py"
click node_chat "https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/components/chat_mixin.py"
click node_gems "https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/components/gem_mixin.py"
click node_research "https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/components/research_mixin.py"
click node_extensions "https://github.com/hanaokayuzu/gemini-api/tree/master/src/gemini_webapi/components"
click node_generation "https://github.com/hanaokayuzu/gemini-api/tree/master/src/gemini_webapi/components"
click node_file_upload "https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/utils/upload_file.py"
click node_response_parser "https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/utils/parsing.py"
click node_research_parser "https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/utils/research.py"
click node_outputs "https://github.com/hanaokayuzu/gemini-api/tree/master/src/gemini_webapi/types"
click node_media_download "https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/types/video.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_developer toneBlue
class node_client,node_auth,node_browser_cookies,node_gemini toneAmber
class node_chat,node_gems,node_research,node_extensions,node_generation,node_file_upload toneMint
class node_response_parser,node_research_parser,node_outputs,node_media_download toneRose
```

## Components

### Entry points

- [Command line](https://github.com/hanaokayuzu/gemini-api/blob/master/cli.py): `cli.py`

### Session and transport

- [Gemini client](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/client.py): `src/gemini_webapi/client.py`
- [Authentication](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/utils/get_access_token.py): `src/gemini_webapi/utils/get_access_token.py`
- [Browser cookies](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/utils/load_browser_cookies.py): `src/gemini_webapi/utils/load_browser_cookies.py`
- **Gemini web app**

### Gemini capabilities

- [Chat and history](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/components/chat_mixin.py): `src/gemini_webapi/components/chat_mixin.py`
- [Gems management](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/components/gem_mixin.py): `src/gemini_webapi/components/gem_mixin.py`
- [Deep Research](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/components/research_mixin.py): `src/gemini_webapi/components/research_mixin.py`
- [Extensions](https://github.com/hanaokayuzu/gemini-api/tree/master/src/gemini_webapi/components): `src/gemini_webapi/components`
- [Media generation](https://github.com/hanaokayuzu/gemini-api/tree/master/src/gemini_webapi/components): `src/gemini_webapi/components`
- [File upload](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/utils/upload_file.py): `src/gemini_webapi/utils/upload_file.py`

### Parsing and outputs

- [Response parsing](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/utils/parsing.py): `src/gemini_webapi/utils/parsing.py`
- [Research extraction](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/utils/research.py): `src/gemini_webapi/utils/research.py`
- [Typed outputs](https://github.com/hanaokayuzu/gemini-api/tree/master/src/gemini_webapi/types): `src/gemini_webapi/types`
- [Media downloads](https://github.com/hanaokayuzu/gemini-api/blob/master/src/gemini_webapi/types/video.py): `src/gemini_webapi/types/video.py`

### Other components

- **API user**

## Connections

- API user → Gemini client: calls
- API user → Command line: runs
- Command line → Gemini client: commands
- Gemini client → Authentication: authenticates
- Authentication → Browser cookies: loads optionally
- Authentication → Gemini web app: requests session
- Gemini client → Gemini web app: sends requests
- Gemini web app → Gemini client: returns frames
- Gemini client → File upload: uploads files
- Gemini client → Response parsing: parses responses
- Response parsing → Typed outputs: builds outputs
- Gemini client → Chat and history: provides chat
- Chat and history → Gemini client: uses transport
- Gemini client → Gems management: provides gem API
- Gemini client → Deep Research: provides research API
- Deep Research → Chat and history: sends turns
- Deep Research → Research extraction: extracts reports
- Deep Research → Typed outputs: returns plan and result
- Gemini client → Extensions: supports generation
- Gemini client → Media generation: supports generation
- Typed outputs → Media downloads: saves generated media