quickstarts/Template.ipynb

{ "cells": [ { "cell_type": "markdown", "metadata": { "id": "Tce3stUlHN0L" }, "source": [ "##### Copyright 2025 Google LLC." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "cellView": "form", "id": "tuOe1ymfHZPu" }, "outputs": [], "source": [ "#@title Licensed under the Apache License, Version 2.0 (the \"License\");\n", "# you may not use this file except in compliance with the License.\n", "# You may obtain a copy of the License at\n", "#\n", "# https://www.apache.org/licenses/LICENSE-2.0\n", "#\n", "# Unless required by applicable law or agreed to in writing, software\n", "# distributed under the License is distributed on an \"AS IS\" BASIS,\n", "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n", "# See the License for the specific language governing permissions and\n", "# limitations under the License." ] }, { "cell_type": "markdown", "metadata": { "id": "qFdPvlXBOdUN" }, "source": [ "# Gemini API: Name of your guide" ] }, { "cell_type": "markdown", "metadata": { "id": "MfBg1C5NB3X0" }, "source": [ "<a target=\"_blank\" href=\"https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Template.ipynb\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" height=30/></a>" ] }, { "cell_type": "markdown", "metadata": { "id": "r6P32iYYV27b" }, "source": [ "_[remove me] Be sure to update the Colab link!_" ] }, { "cell_type": "markdown", "metadata": { "id": "XCVydW40iixa" }, "source": [ "[If you're adding a new example, use this badge to promote yourself (yes sorry you'll have to write your name a lot of times)]\n", "\n", "<table>\n", " <tr>\n", " \n", " <td bgcolor=\"#d7e6ff\">\n", " <a href=\"https://github.com/Giom-V\" target=\"_blank\" title=\"View Guillaume's profile on GitHub\">\n", " <img src=\"https://github.com/Giom-V.png?size=100\"\n", " alt=\"Giom-V's GitHub avatar\"\n", " width=\"100\"\n", " height=\"100\">\n", " </a>\n", " </td>\n", " \n", " <td bgcolor=\"#d7e6ff\">\n", " <h2><font color='black'>This notebook was contributed by <a href=\"https://github.com/Giom-V\" target=\"_blank\"><font color='#217bfe'><strong>Giom (use either your GitHub handle or your real name, your choice)</strong></font></a>.</font></h2>\n", " <h5><font color='black'><a href=\"URL\"><font color=\"#078efb\">Add a link to you blog, or linkedIn, or something else</font></a> - See <a href=\"https://github.com/Giom-V\" target=\"_blank\"><font color=\"#078efb\"><strong>Giom</strong></font></a> other notebooks <a href=\"https://github.com/search?q=repo%3Agoogle-gemini%2Fcookbook%20%22Giom%22&type=code\" target=\"_blank\"><font color=\"#078efb\">here</font></a>.</h5></font><br>\n", " \n", " <font color='black'><small><em>Have a cool Gemini example? Feel free to <a href=\"https://github.com/google-gemini/cookbook/blob/main/CONTRIBUTING.md\" target=\"_blank\"><font color=\"#078efb\">share it too</font></a>!</em></small></font>\n", " </td>\n", " </tr>\n", "</table>" ] }, { "cell_type": "markdown", "metadata": { "id": "6b527162" }, "source": [ "[Depending on the cases you might also want to add a badge like that as a disclaimer]\n", "\n", "\n", "<table>\n", " <tr>\n", " \n", " <td bgcolor=\"#f5949e\">\n", " <font size=30>⚠️</font>\n", " </td>\n", " \n", " <td bgcolor=\"#f5949e\">\n", " <h3><font color=black>Image generation is a paid-only feature and won't work if you are on the free tier. Check the <a href=\"https://ai.google.dev/pricing#imagen3\"><font color='#217bfe'>pricing</font></a> page for more details.</font></h3>\n", " </td>\n", " </tr>\n", "</table>\n", "\n", "\n", "<table align=\"left\" border=\"3\">\n", " <tr>\n", " \n", " <td bgcolor=\"#DCE2FF\">\n", " <font size=30>🪧</font>\n", " </td>\n", " \n", " <td bgcolor=\"#DCE2FF\">\n", " <h4><font color=black>Image-out is a preview feature. It is free to use for now with quota limitations, but is subject to change.</font></h4>\n", " </td>\n", " </tr>\n", "</table>" ] }, { "cell_type": "markdown", "metadata": { "id": "xHxb-dlhMIzW" }, "source": [ "[Include a paragraph or two here explaining what this example demonstrates, who should be interested in it, and what you need to know before you get started.]" ] }, { "cell_type": "markdown", "metadata": { "id": "monLpKy7423V" }, "source": [ "## Setup" ] }, { "cell_type": "markdown", "metadata": { "id": "5mi7BrkD44MF" }, "source": [ "### Install SDK" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "AQJjzmYgH3sX" }, "outputs": [], "source": [ "%pip install -U -q \"google-genai>=1.0.0\" # Install the Python SDK\n", "\n", "# Always set at least 1.0.0 as the minimal version as there were breaking\n", "# changes through the previous versions\n", "# Of course, if your notebook uses a new feature and needs a more recent\n", "# version, set the right minimum version to indicate when the feature was\n", "# introduced.\n", "# Always test your notebook with that fixed version (eg. '==1.0.0') to make.\n", "# sure it's really the minimum version.\n" ] }, { "cell_type": "markdown", "metadata": { "id": "MUXex9ctTuDB" }, "source": [ "### Set up your API key\n", "\n", "To run the following cell, your API key must be stored it in a Colab Secret named `GOOGLE_API_KEY`. If you don't already have an API key, or you're not sure how to create a Colab Secret, see the [Authentication](../quickstarts/Authentication.ipynb) quickstart for an example." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "wltbMJLIIXGk" }, "outputs": [], "source": [ "from google.colab import userdata\n", "from google import genai\n", "\n", "GOOGLE_API_KEY = userdata.get('GOOGLE_API_KEY')\n", "client = genai.Client(api_key=GOOGLE_API_KEY)" ] }, { "cell_type": "markdown", "metadata": { "id": "hL54YG-kMDVF" }, "source": [ "Now select the model you want to use in this guide, either by selecting one in the list or writing it down. Keep in mind that some models, like the 2.5 ones are thinking models and thus take slightly more time to respond (cf. [thinking notebook](./Get_started_thinking.ipynb) for more details and in particular learn how to switch the thiking off)." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "Lf6FamchMDsk" }, "outputs": [], "source": [ "MODEL_ID = \"gemini-2.5-flash\" # @param [\"gemini-2.5-flash-lite-preview-06-17\",\"gemini-2.0-flash\",\"gemini-2.5-flash\",\"gemini-2.5-pro\"] {\"allow-input\":true, isTemplate: true}\n", "\n", "# Ideally order the model by \"cabability\" ie. generation then within generation\n", "# 8b/flash-lite then flash then pro" ] }, { "cell_type": "markdown", "metadata": { "id": "w5i8tMZKIeUu" }, "source": [ "## [Write your guide]\n", "\n", "[Add as many high level sections as needed to step through your guide. Try to introduce new concepts incrementally, including explanatory text at every step. Remember that notebooks need to be executable from start to finish using `Runtime -> Run all` in Colab.]" ] }, { "cell_type": "markdown", "metadata": { "id": "4677dd58e9b5" }, "source": [ "## Next Steps\n", "### Useful API references:\n", "\n", "[Always end with links to the related doumentation]\n", "\n", "### Related examples\n", "\n", "[If any, add links to the related examples]\n", "\n", "### Continue your discovery of the Gemini API\n", "\n", "[Finally, link some other quickstarts that are either related or require the same level of expertise]\n" ] }, { "cell_type": "markdown", "metadata": { "id": "UhNtHfuxCGVy" }, "source": [ "# Resources (don't forget to delete everything starting from here)\n", "\n", "* Follow the [Google developer documentation style guide](https://developers.google.com/style/highlights)\n", "* The [TensorFlow documentation style guide](https://www.tensorflow.org/community/contribute/docs_style) has useful guidance for notebooks.\n", "* Read the [Cookbook contributor guide](https://github.com/google-gemini/cookbook/blob/main/CONTRIBUTING.md) and the [Cookbook Examples contributor guide](https://github.com/google-gemini/cookbook/blob/main/examples/CONTRIBUTING.md)." ] }, { "cell_type": "markdown", "metadata": { "id": "2V22fKegUtF9" }, "source": [ "## Notebook style (also check the [Contributing guide](Contributing.mg))\n", "\n", "* Include the collapsed license at the top (uses the Colab \"Form\" mode to hide the cells).\n", "* Save the notebook with the table of contents open.\n", "* Use one `H1` header for the title.\n", "* Include the button-bar immediately after the `H1`.\n", "* Include an overview section before any code.\n", "* Keep your installs and imports close to the code that first uses them. If they are used throughout (such as the SDK), they can go at the start of the guide.\n", "* Keep code and text cells as brief as possible.\n", "* Break text cells at headings\n", "* Break code cells between \"building\" and \"running\", and between \"printing one result\" and \"printing another result\".\n", "* Necessary but uninteresting code should be hidden in a toggleable code cell by putting `# @title` as the first line.\n", "* You can optionally add a byline for content in `examples/` that you wrote, including one link to your GitHub, social, or site of your choice." ] }, { "cell_type": "markdown", "metadata": { "id": "QKp40qS-DGEZ" }, "source": [ "### Code style\n", "\n", "* Notebooks are for people. Write code optimized for clarity.\n", "* Keep examples quick and concise.\n", "* Use the [Google Python Style Guide](http://google.github.io/styleguide/pyguide.html), where applicable. Code formatted by [`pyink`](https://github.com/google/pyink) will always be accepted.\n", "* In particular, defining functions and variables takes extra spaces around the `=` sign, while function parameters don't:\n", "```python\n", " var = value\n", " function(\n", " parameter=value\n", " )\n", "```\n", "* If you define a function, run it and show us what it does before using it in another function.\n", "* Demonstrate small parts before combining them into something more complex.\n", "* Keep the code as simple as possible, only use extra parameters like temperature when needed, and in that case, explain why\n", "* To ensure notebook text remains accurate, present model metadata by executing code.\n", " * For example, instead of saying \"1M token context\" in the text, display the output of `client.models.get(model='...').input_token_limit`.\n" ] }, { "cell_type": "markdown", "metadata": { "id": "78HBT9cQXJko" }, "source": [ "### Text\n", "\n", "* Use an imperative style. \"Run a prompt using the API.\"\n", "* Use sentence case in titles/headings.\n", "* Use short titles/headings: \"Download the data\", \"Call the API\", \"Process the results\".\n", "* Use the [Google developer documentation style guide](https://developers.google.com/style/highlights).\n", "* Use [second person](https://developers.google.com/style/person): \"you\" rather than \"we\".\n", "* When using links between notebooks, use relative ones as they'll work better in IDEs and Colab. Use absolute ones to link to folders or markdown files.\n" ] }, { "cell_type": "markdown", "metadata": { "id": "YrsKXcPRUvK9" }, "source": [ "## GitHub workflow\n", "\n", "* Be consistent about how you save your notebooks, otherwise the JSON diffs are messy. [`nbfmt` and `nblint`](https://github.com/tensorflow/docs/blob/master/tools/tensorflow_docs/tools/README.md) help here.\n", "* This notebook has the \"Omit code cell output when saving this notebook\" option set. GitHub refuses to diff notebooks with large diffs (inline images).\n", "* [ReviewNB.com](http://reviewnb.com) can help with diffs. This is linked in a comment on a notebook pull request.\n", "* Use the [Open in Colab](https://chrome.google.com/webstore/detail/open-in-colab/iogfkhleblhcpcekbiedikdehleodpjo) extension to open a GitHub notebook in Colab.\n", "* The easiest way to edit a notebook in GitHub is to open it with Colab from the branch you want to edit. Then use File --> Save a copy in GitHub, which will save it back to the branch you opened it from.\n", "* For PRs it's helpful to post a direct Colab link to the PR head: https://colab.research.google.com/github/{USER}/{REPO}/blob/{BRANCH}/{PATH}.ipynb" ] } ], "metadata": { "colab": { "collapsed_sections": [ "Tce3stUlHN0L" ], "name": "Template.ipynb", "toc_visible": true }, "kernelspec": { "display_name": "Python 3", "name": "python3" } }, "nbformat": 4, "nbformat_minor": 0 }

quickstarts/Template.ipynb (361 lines of code) (raw):