Skip to content

Gemini API

The Gemini endpoint lets you send a text prompt to a Gemini model and receive an AI-generated answer in real time. This guide covers the single endpoint, the two required inputs, the optional controls that shape the response, and the credit and retry rules you need to plan around.

Overview

The API exposes one route: the Gemini endpoint at /api/v1/gemini. You send a prompt and receive a generated response. Two inputs are mandatory: your API key and a prompt. Everything else is optional and changes how the response is packaged or how the request is labeled.

A quick-start example is shown below. The exact request contract is preserved in the accompanying protected modules, so treat the code blocks as the authoritative reference for headers, query parameters and response fields.

Quick start

To make your first call you need an API key and a prompt. The key is sent as a Bearer token in the Authorization header. The prompt is passed as the prompt query parameter. The example below uses the prompt "Best programming languages for data science" and returns a JSON body.

The request contract, including the exact header and parameter names, is preserved in the protected modules referenced at the end of this page.

Parameters

The table below maps each parameter to its type, default and role. Required fields must be present on every call; optional fields can be omitted and fall back to their defaults.

Response example

A successful call returns formatted JSON. The body includes the original prompt, a Markdown version of the answer, a plain-text version, and a citations array. When add_html=true is set, a full_html field is also included. The exact response shape is preserved in the protected module for this section.

API key

All requests are authenticated with your private API key, sent as a Bearer token in the Authorization header. To obtain a key, create an account and confirm your email address. The full authentication details, including the deprecated api_key query parameter, are covered in the authentication documentation.

Prompt

The prompt parameter is the text sent to the Gemini model for processing. It is required for the Gemini endpoint. Clear, specific prompts tend to produce better results; you can ask questions, request content generation, or ask for analysis on a topic.

Prompt best practices

Four habits improve prompt quality: be specific, provide context, set expectations for format or style, and show examples of the output you want. Example prompts include summarizing text in three bullet points, drafting a professional email response, explaining a technical topic in simple terms, and generating product name ideas.

Add HTML

The add_html parameter controls whether the full HTML is included alongside the text answer. When set to true, the response contains a full_html field with the complete HTML content. The default is false, which omits it.

Country code

The country_code parameter sets the geolocation for the request using an ISO country code such as us, gb or fr.

Tag

The tag parameter attaches a custom string identifier to a request. The value is returned with the response headers. It is optional and does not affect scraping behavior.

Credit cost for your requests

Each plan provides a monthly allotment of API credits. The credit cost per Gemini API request is set by the service owner: {{OWNER_CREDIT_COST}}.

Citations

Citations are not guaranteed on every response. Whether they appear depends on the prompt; they are more likely when the answer is web-grounded rather than a general-knowledge request.

Parameter map
ParameterTypeDefaultRequiredRole
api_keystring—YesYour API key
promptstring—YesText sent to the Gemini model
add_htmlbooleanfalseNoInclude full HTML in the response
country_codestring""NoISO country code for request geolocation
tagstring""NoCustom identifier returned with response headers

Defaults reflect the values shown in the parameter reference. The api_key and prompt fields are required; the others are optional.

Frequently asked questions

What do I need to make a Gemini API call?

An API key and a prompt. The key is sent as a Bearer token in the Authorization header, and the prompt is passed as the prompt parameter.

How many credits does a Gemini API request cost?

The credit cost per request is set by the service owner: {{OWNER_CREDIT_COST}}.

What happens if a request fails?

Failed requests are retried for a window set by the service owner: {{OWNER_RETRY_WINDOW}}. Plan your own client timeouts around that maximum window.

Will every response include citations?

No. Citations are not returned 100% of the time. They depend on the prompt and are more likely when the answer is web-grounded rather than general knowledge.

When should I set add_html to true?

Set add_html=true when you need the full HTML content in the response alongside the text answer. Leave it at the default false to omit the full_html field.

curl "{{APP_BASE_URL}}/api/v1/gemini?prompt=Best+programming+languages+for+data+science" \
     -H "Authorization: Bearer YOUR-API-KEY"
{
    "full_html": "" # Full HTML response, including all formatting, included if add_html=true
    "prompt": "Best programming languages for data science",
    # The result in Markdown format
    "results_markdown": "When it comes to data science, you don\u2019t need to learn every programming language out there. The industry is highly consolidated around a few heavy hitters, though the \"best\" language ultimately depends on whether you are building machine learning models, running statistical research, or engineering massive data pipelines.\n\nThe top programming languages for data science are broken down below, ranked by relevance and use case.\n\n1. The Heavy Hitters (The Non-Negotiables)\n------------------------------------------\n\nIf you are just getting started, focus your energy here. These two languages form the backbone of the vast majority of data science jobs.\n\n### **Python**\n\n* **The Verdict:** The undisputed king of data science.\n* **Why it\u2019s great:** Python is a general-purpose language with an English-like syntax that is incredibly beginner-friendly. Its real power lies in its massive, mature ecosystem of libraries. Whether you want to clean data, build deep learning models, or deploy an API, Python has a tool for it.\n* \n\n### **SQL (Structured Query Language)**\n\n* **The Verdict:** Absolutely non-negotiable.\n* **Why it\u2019s great:** SQL isn't for building machine learning models, but it is how you talk to databases. Before you can analyze data or train a model, you have to extract the data. Data scientists frequently use SQL to pull, filter, and aggregate millions of rows of data before passing it into Python or R.\n* **Best for:** Data extraction, querying, and database management.\n\n",
    # The result in plain text format
    "results_text": "When it comes to data science, you don\u2019t need to learn every programming language out there. The industry is highly consolidated around a few heavy hitters, though the \"best\" language ultimately depends on whether you are building machine learning models, running statistical research, or engineering massive data pipelines. The top programming languages for data science are broken down below, ranked by relevance and use case. 1. The Heavy Hitters (The Non-Negotiables) If you are just getting started, focus your energy here. These two languages form the backbone of the vast majority of data science jobs. Python The Verdict: The undisputed king of data science. Why it\u2019s great: Python is a general-purpose language with an English-like syntax that is incredibly beginner-friendly. Its real power lies in its massive, mature ecosystem of libraries. Whether you want to clean data, build deep learning models, or deploy an API, Python has a tool for it. SQL (Structured Query Language) The Verdict: Absolutely non-negotiable. Why it\u2019s great: SQL isn't for building machine learning models, but it is how you talk to databases. Before you can analyze data or train a model, you have to extract the data. Data scientists frequently use SQL to pull, filter, and aggregate millions of rows of data before passing it into Python or R. Best for: Data extraction, querying, and database management.",
    # Source citations referenced in the response
    "citations": [
        {
            "description": "Example post details.",
            "text": "An example comment.",
            "title": "The 10 Best Programming Languages for Data Science | Intuit Blog",
            "url": "https://www.intuit.com/blog/innovative-thinking/best-programming-languages-for-data-science/"
        },
        {
            "description": "Example post details.",
            "text": "An example comment.",
            "title": "The 10 Best Programming Languages for Data Science | Intuit Blog",
            "url": "https://www.intuit.com/blog/innovative-thinking/best-programming-languages-for-data-science/"
        },
        {
            "description": "Example post details.",
            "text": "An example comment.",
            "title": "The 10 Best Programming Languages for Data Science | Intuit Blog",
            "url": "https://www.intuit.com/blog/innovative-thinking/best-programming-languages-for-data-science/#:~:text=1.,for%20many%20data%20science%20jobs."
        }
    ],
}
curl "{{APP_BASE_URL}}/api/v1/gemini?prompt=Best+programming+languages+for+data+science" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/gemini?add_html=true&prompt=Explain+the+benefits+of+renewable+energy+in+100+words" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/gemini?country_code=us&prompt=What+are+the+top+news+stories+today%3F" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/gemini?prompt=What+is+the+weather+today%3F&tag=your+text" \
     -H "Authorization: Bearer YOUR-API-KEY"