🚀 A Python library for interacting with Grok 3 API without login or cookies required. Perfect for using out of the box.
## [➡️ Russian ReadMe](docs/Ru/RuReadMe.md)
# Grok3API: Client for Working with Grok 🤖
**Grok3API** is a powerful and convenient unofficial client for interacting with Grok models (including Grok3), allowing you to send requests, receive text responses, and, most notably, **generated images** — all with automatic cookie management! 🎨✨ The project is designed with a focus on ease of use and automation, so you can concentrate on creativity rather than technical details.
---
## 🌟 Features
- 🚀 **Automatic cookie retrieval** via browser with bypassing Cloudflare — no manual setup required!
- 🖼️ **Convenient retrieval of generated images** with the `save_to` method, enabling you to save them with a single click.
- 🔄 **Automatic cookie updates** for errors like "Too Many Requests" or "Unauthorized".
- 🔧 **Flexible request configuration**: model selection, image generation management, attachment addition, and more.
- 📦 **Attachment support**: send files and images along with your requests.
- 🛠️ **Error handling**: the client resolves cookie issues and retries requests if something goes wrong.
- 🤖 **[Telegram bot example](tests/SimpleTgBot/SimpleTgBot.py) (`grok3api` + `aiogram`)**, with the ability to create text replies and images.
---
## 📦 Installation
To start using Grok3API, install the necessary dependencies. It’s simple:
```bash
pip install grok3api
```
> ⚠️ **Important**: Ensure you have **Google Chrome** installed, as `undetected_chromedriver` works specifically with it.
After installing, you’re ready to begin! 🎉
---
## 🚀 Usage
### Quick Start
Here’s a complete example of how to send a request and save a generated image:
```python
from grok3api.client import GrokClient
def main():
# Create a client (cookies will be automatically retrieved if not present)
client = GrokClient()
# Create a request
message = "Create an image of a ship"
# Send the request
result = client.send_message(message)
print("Grok's response:", result.modelResponse.message)
# Save the first image if available
if result.modelResponse.generatedImages:
result.modelResponse.generatedImages[0].save_to("ship.jpg")
print("Image saved as ship.jpg! 🚀")
if __name__ == '__main__':
main()
```
This code:
1. Creates a client (cookies are fetched automatically if absent).
2. Sends a request to generate an image.
3. Saves the result to the file `ship.jpg`.
**📌 What will we see?**
Grok will generate an image of a **ship**, for example, something like this:
<img src="assets/ship.jpg" alt="Example spaceship" width="500">
> 💡 **Tip**: You don’t need to manually obtain cookies — the client handles it for you!
---
## 🔧 Request Parameters
The `GrokCLient.send_message` method accepts numerous parameters to customize your request. Here’s an example with settings:
```python
from grok3api.client import GrokClient
def main():
# Create a client
client = GrokClient()
# Send a request with settings
result = client.send_message(
message="Draw a cat",
modelName="grok-3", # Default is grok-3
imageGenerationCount=2, # I want 2 cat images!
)
print(f"Grok3's response: {result.modelResponse.message}")
# Save all images
for i, img in enumerate(result.modelResponse.generatedImages):
img.save_to(f"cat_{i}.jpg")
print(f"Saved: cat_{i}.jpg 🐾")
if __name__ == '__main__':
main()
```
### [💼️ Descriptions of the `CrokClient` class](docs/En/ClientDoc.md)
### [✈️ Descriptions of the `send_message` method](docs/En/sendMessageDoc)
### [📋 Description of the `History` class](docs/En/HistoryDoc.md)
### [📬 Descriptions of the `GrokResponse` class](docs/En/GrokResponse.md)
### [🐧 Working with `Linux`](docs/En/LinuxDoc.md)
---
## 🖼️ Convenient Image Handling
One of the standout features of GrokClient is its **super-convenient handling of generated images**. Here’s a complete example:
```python
from grok3api.client import GrokClient
def main():
# Create a client
client = GrokClient()
# Send a request
result = client.send_message("Draw a sunset over the sea")
# Save all images
for i, image in enumerate(result.modelResponse.generatedImages):
image.save_to(f"sunset_{i}.jpg")
print(f"Saved: sunset_{i}.jpg 🌅")
if __name__ == '__main__':
main()
```
> 🌟 **Cool Fact**: This works with automatically retrieved cookies! You don’t need to worry about access — the client sets everything up for you.
---
## 🔄 Automatic Cookie Retrieval
If cookies are missing or outdated, GrokClient automatically:
1. Uses a Chrome browser (ensure it’s installed).
2. Visits `https://grok.com/`.
3. Bypasses Cloudflare protection.
4. Will continue to work.
You don’t need to do anything manually — just run the code, and it will work!
---
## 📋 Response Processing
The `send_message` method returns a `GrokResponse` object. Here’s an example of working with it:
```python
from grok3api.client import GrokClient
def main():
# Create a client
client = GrokClient()
# Send a request
result = client.send_message("Describe and draw a forest")
# Process the response
print(f"Text: {result.modelResponse.message}")
if result.modelResponse.generatedImages:
result.modelResponse.generatedImages[0].save_to("forest.jpg")
if __name__ == '__main__':
main()
```
**Fields of the `GrokResponse` object:**
- **`modelResponse`**: The main model response.
- `message` (str): The text response.
- `generatedImages` (List[GeneratedImage]): List of images.
- **`isThinking`**: Whether the model was thinking (bool).
- **`isSoftStop`**: Soft stop (bool).
- **`responseId`**: Response ID (str).
- **`newTitle`**: New chat title, if available (Optional[str]).
---
## 🚨 Error Handling
GrokClient is equipped to handle issues:
- **HTTP 429 (Too Many Requests)**: Automatically updates cookies and retries the request.
- **Missing cookies**: Retrieves them via the browser.
- **Other errors**: Logged for debugging.
---
## 📄 License
The project is distributed under the **MIT** license. Details are available in the [LICENSE](LICENSE) file.
If anything is unclear, feel free to open an issue — we’ll sort it out together! 🌟
---
## Disclaimer
### Introduction
Grok3API is a third-party client for interacting with Grok.
Grok3API has no affiliation with xAI or the developers of Grok. It is an independent project created by a third party and is not supported, sponsored, or endorsed by xAI. Any issues related to the Grok API should be addressed directly to xAI.
### Responsibility and Warranties
The software is provided "as is," without any warranties, including fitness for a particular purpose or absence of errors. The creator of Grok3API is not liable for any losses or damages resulting from the use of the client. You use it at your own risk.
### Compliance with Laws
You are responsible for ensuring that your use of Grok3API complies with all applicable laws and regulations. The creator does not encourage illegal use.
Grok3API requires full compliance with the xAI API rules.
Raw data
{
"_id": null,
"home_page": "https://github.com/boykopovar/Grok3API",
"name": "Grok3API",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "grok3, grok 3 api, grok api, grok3 python, grok ai, unofficial grok3 api",
"author": "boykopovar",
"author_email": "boykopovar <boykopovar@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/72/dd/bf3d24e0848471e53a9cc4dab8cf120b5789cbc0a195ac4fc294af34ffdb/grok3api-0.0.1a15.tar.gz",
"platform": null,
"description": "\ud83d\ude80 A Python library for interacting with Grok 3 API without login or cookies required. Perfect for using out of the box.\r\n\r\n## [\u27a1\ufe0f Russian ReadMe](docs/Ru/RuReadMe.md)\r\n\r\n# Grok3API: Client for Working with Grok \ud83e\udd16\r\n\r\n\r\n\r\n**Grok3API** is a powerful and convenient unofficial client for interacting with Grok models (including Grok3), allowing you to send requests, receive text responses, and, most notably, **generated images** \u2014 all with automatic cookie management! \ud83c\udfa8\u2728 The project is designed with a focus on ease of use and automation, so you can concentrate on creativity rather than technical details.\r\n\r\n---\r\n\r\n## \ud83c\udf1f Features\r\n\r\n- \ud83d\ude80 **Automatic cookie retrieval** via browser with bypassing Cloudflare \u2014 no manual setup required!\r\n- \ud83d\uddbc\ufe0f **Convenient retrieval of generated images** with the `save_to` method, enabling you to save them with a single click.\r\n- \ud83d\udd04 **Automatic cookie updates** for errors like \"Too Many Requests\" or \"Unauthorized\".\r\n- \ud83d\udd27 **Flexible request configuration**: model selection, image generation management, attachment addition, and more.\r\n- \ud83d\udce6 **Attachment support**: send files and images along with your requests.\r\n- \ud83d\udee0\ufe0f **Error handling**: the client resolves cookie issues and retries requests if something goes wrong.\r\n- \ud83e\udd16 **[Telegram bot example](tests/SimpleTgBot/SimpleTgBot.py) (`grok3api` + `aiogram`)**, with the ability to create text replies and images.\r\n\r\n---\r\n\r\n## \ud83d\udce6 Installation\r\n\r\nTo start using Grok3API, install the necessary dependencies. It\u2019s simple:\r\n\r\n```bash\r\npip install grok3api\r\n```\r\n\r\n> \u26a0\ufe0f **Important**: Ensure you have **Google Chrome** installed, as `undetected_chromedriver` works specifically with it.\r\n\r\nAfter installing, you\u2019re ready to begin! \ud83c\udf89\r\n\r\n---\r\n\r\n## \ud83d\ude80 Usage\r\n\r\n### Quick Start\r\n\r\nHere\u2019s a complete example of how to send a request and save a generated image:\r\n\r\n```python\r\nfrom grok3api.client import GrokClient\r\n\r\n\r\ndef main():\r\n # Create a client (cookies will be automatically retrieved if not present)\r\n client = GrokClient()\r\n\r\n # Create a request\r\n message = \"Create an image of a ship\"\r\n\r\n # Send the request\r\n result = client.send_message(message)\r\n print(\"Grok's response:\", result.modelResponse.message)\r\n\r\n # Save the first image if available\r\n if result.modelResponse.generatedImages:\r\n result.modelResponse.generatedImages[0].save_to(\"ship.jpg\")\r\n print(\"Image saved as ship.jpg! \ud83d\ude80\")\r\n\r\n\r\nif __name__ == '__main__':\r\n main()\r\n```\r\n\r\nThis code:\r\n1. Creates a client (cookies are fetched automatically if absent).\r\n2. Sends a request to generate an image.\r\n3. Saves the result to the file `ship.jpg`.\r\n\r\n**\ud83d\udccc What will we see?** \r\nGrok will generate an image of a **ship**, for example, something like this: \r\n\r\n<img src=\"assets/ship.jpg\" alt=\"Example spaceship\" width=\"500\">\r\n\r\n> \ud83d\udca1 **Tip**: You don\u2019t need to manually obtain cookies \u2014 the client handles it for you!\r\n\r\n---\r\n\r\n## \ud83d\udd27 Request Parameters\r\n\r\nThe `GrokCLient.send_message` method accepts numerous parameters to customize your request. Here\u2019s an example with settings:\r\n\r\n```python\r\nfrom grok3api.client import GrokClient\r\n\r\n\r\ndef main():\r\n # Create a client\r\n client = GrokClient()\r\n\r\n # Send a request with settings\r\n result = client.send_message(\r\n message=\"Draw a cat\",\r\n modelName=\"grok-3\", # Default is grok-3\r\n imageGenerationCount=2, # I want 2 cat images!\r\n )\r\n print(f\"Grok3's response: {result.modelResponse.message}\")\r\n\r\n # Save all images\r\n for i, img in enumerate(result.modelResponse.generatedImages):\r\n img.save_to(f\"cat_{i}.jpg\")\r\n print(f\"Saved: cat_{i}.jpg \ud83d\udc3e\")\r\n\r\n\r\nif __name__ == '__main__':\r\n main()\r\n```\r\n\r\n\r\n### [\ud83d\udcbc\ufe0f Descriptions of the `CrokClient` class](docs/En/ClientDoc.md)\r\n### [\u2708\ufe0f Descriptions of the `send_message` method](docs/En/sendMessageDoc)\r\n### [\ud83d\udccb Description of the `History` class](docs/En/HistoryDoc.md)\r\n### [\ud83d\udcec Descriptions of the `GrokResponse` class](docs/En/GrokResponse.md)\r\n### [\ud83d\udc27 Working with `Linux`](docs/En/LinuxDoc.md)\r\n\r\n---\r\n\r\n## \ud83d\uddbc\ufe0f Convenient Image Handling\r\n\r\nOne of the standout features of GrokClient is its **super-convenient handling of generated images**. Here\u2019s a complete example:\r\n\r\n```python\r\nfrom grok3api.client import GrokClient\r\n\r\n\r\ndef main():\r\n # Create a client\r\n client = GrokClient()\r\n\r\n # Send a request\r\n result = client.send_message(\"Draw a sunset over the sea\")\r\n\r\n # Save all images\r\n for i, image in enumerate(result.modelResponse.generatedImages):\r\n image.save_to(f\"sunset_{i}.jpg\")\r\n print(f\"Saved: sunset_{i}.jpg \ud83c\udf05\")\r\n\r\n\r\nif __name__ == '__main__':\r\n main()\r\n```\r\n\r\n> \ud83c\udf1f **Cool Fact**: This works with automatically retrieved cookies! You don\u2019t need to worry about access \u2014 the client sets everything up for you.\r\n\r\n---\r\n\r\n## \ud83d\udd04 Automatic Cookie Retrieval\r\n\r\nIf cookies are missing or outdated, GrokClient automatically:\r\n1. Uses a Chrome browser (ensure it\u2019s installed).\r\n2. Visits `https://grok.com/`.\r\n3. Bypasses Cloudflare protection.\r\n4. Will continue to work.\r\n\r\nYou don\u2019t need to do anything manually \u2014 just run the code, and it will work!\r\n\r\n\r\n\r\n---\r\n\r\n## \ud83d\udccb Response Processing\r\n\r\nThe `send_message` method returns a `GrokResponse` object. Here\u2019s an example of working with it:\r\n\r\n```python\r\nfrom grok3api.client import GrokClient\r\n\r\n\r\ndef main():\r\n # Create a client\r\n client = GrokClient()\r\n\r\n # Send a request\r\n result = client.send_message(\"Describe and draw a forest\")\r\n\r\n # Process the response\r\n print(f\"Text: {result.modelResponse.message}\")\r\n if result.modelResponse.generatedImages:\r\n result.modelResponse.generatedImages[0].save_to(\"forest.jpg\")\r\n\r\n\r\nif __name__ == '__main__':\r\n main()\r\n```\r\n\r\n**Fields of the `GrokResponse` object:**\r\n- **`modelResponse`**: The main model response.\r\n - `message` (str): The text response.\r\n - `generatedImages` (List[GeneratedImage]): List of images.\r\n- **`isThinking`**: Whether the model was thinking (bool).\r\n- **`isSoftStop`**: Soft stop (bool).\r\n- **`responseId`**: Response ID (str).\r\n- **`newTitle`**: New chat title, if available (Optional[str]).\r\n\r\n---\r\n\r\n## \ud83d\udea8 Error Handling\r\n\r\nGrokClient is equipped to handle issues:\r\n- **HTTP 429 (Too Many Requests)**: Automatically updates cookies and retries the request.\r\n- **Missing cookies**: Retrieves them via the browser.\r\n- **Other errors**: Logged for debugging.\r\n\r\n---\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThe project is distributed under the **MIT** license. Details are available in the [LICENSE](LICENSE) file.\r\n\r\nIf anything is unclear, feel free to open an issue \u2014 we\u2019ll sort it out together! \ud83c\udf1f\r\n\r\n---\r\n\r\n## Disclaimer\r\n\r\n### Introduction\r\n\r\nGrok3API is a third-party client for interacting with Grok.\r\n\r\nGrok3API has no affiliation with xAI or the developers of Grok. It is an independent project created by a third party and is not supported, sponsored, or endorsed by xAI. Any issues related to the Grok API should be addressed directly to xAI.\r\n\r\n### Responsibility and Warranties\r\n\r\nThe software is provided \"as is,\" without any warranties, including fitness for a particular purpose or absence of errors. The creator of Grok3API is not liable for any losses or damages resulting from the use of the client. You use it at your own risk.\r\n\r\n### Compliance with Laws\r\n\r\nYou are responsible for ensuring that your use of Grok3API complies with all applicable laws and regulations. The creator does not encourage illegal use.\r\n\r\nGrok3API requires full compliance with the xAI API rules.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python-\u0431\u0438\u0431\u043b\u0438\u043e\u0442\u0435\u043a\u0430 \u0434\u043b\u044f \u0432\u0437\u0430\u0438\u043c\u043e\u0434\u0435\u0439\u0441\u0442\u0432\u0438\u044f \u0441 Grok3 \u0432 \u0441\u0442\u0438\u043b\u0435 OpenAI. \u0410\u0432\u0442\u043e\u043c\u0430\u0442\u0438\u0447\u0435\u0441\u043a\u0438 \u043f\u043e\u043b\u0443\u0447\u0430\u0435\u0442 cookies, \u043f\u043e\u044d\u0442\u043e\u043c\u0443 \u0438\u0445 \u043d\u0435 \u043e\u0431\u044f\u0437\u0430\u0442\u0435\u043b\u044c\u043d\u043e \u0443\u043a\u0430\u0437\u044b\u0432\u0430\u0442\u044c \u0432\u0440\u0443\u0447\u043d\u0443\u044e. A Python library for interacting with Grok3 in the style of OpenAI. Automatically retrieves cookies, so specifying them manually is not required.",
"version": "0.0.1a15",
"project_urls": {
"Homepage": "https://github.com/boykopovar/Grok3API"
},
"split_keywords": [
"grok3",
" grok 3 api",
" grok api",
" grok3 python",
" grok ai",
" unofficial grok3 api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a900bfb961702013f0f2fe31377022dd066a4e6ef43d941069073e30b4519155",
"md5": "1b909adc20b43b4c01d22007838122ce",
"sha256": "bc4293c04bf523cc19b0a3bdae789a582527b68f8942b8bf2d59157d10e1eadf"
},
"downloads": -1,
"filename": "grok3api-0.0.1a15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b909adc20b43b4c01d22007838122ce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 17822,
"upload_time": "2025-03-09T13:12:33",
"upload_time_iso_8601": "2025-03-09T13:12:33.576756Z",
"url": "https://files.pythonhosted.org/packages/a9/00/bfb961702013f0f2fe31377022dd066a4e6ef43d941069073e30b4519155/grok3api-0.0.1a15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "72ddbf3d24e0848471e53a9cc4dab8cf120b5789cbc0a195ac4fc294af34ffdb",
"md5": "db8c91bc727a67a64e6edbda92ba3e21",
"sha256": "33aaf59012274c4e614bd7d035fbb78c04cf2035bf7241d2543e959130bb25ef"
},
"downloads": -1,
"filename": "grok3api-0.0.1a15.tar.gz",
"has_sig": false,
"md5_digest": "db8c91bc727a67a64e6edbda92ba3e21",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 16344,
"upload_time": "2025-03-09T13:12:35",
"upload_time_iso_8601": "2025-03-09T13:12:35.052767Z",
"url": "https://files.pythonhosted.org/packages/72/dd/bf3d24e0848471e53a9cc4dab8cf120b5789cbc0a195ac4fc294af34ffdb/grok3api-0.0.1a15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-09 13:12:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "boykopovar",
"github_project": "Grok3API",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "grok3api"
}
JSON
