Your First Gemini Request | AI Application Building

Your First Real Gemini Request

You have already learned what an API does, explored Google AI Studio, and created an API key.

Now we will connect those pieces and send a real request from this course application to Gemini.

This is the turning point

Until now, the course has explained application development. In this lesson, the course itself becomes a working Gemini application.

What This Exercise Will Do

The interactive tool below follows the same request cycle from Lesson 1:

You enter a prompt.
JavaScript sends the prompt to a PHP endpoint.
PHP validates the request.
PHP loads the private Gemini API key.
PHP sends the request to Gemini.
Gemini returns a response.
PHP extracts the generated text.
JavaScript displays the result.

The browser never receives the API key

The browser sends only the prompt and a security token to PHP. The private API key remains on the server.

Try Your First Request

Enter a simple instruction below or select one of the sample prompts. Then send the request to Gemini.

LIVE GEMINI API EXERCISE

First Request Playground

Send a text prompt through PHP and display the returned Gemini response.

Ready

SAMPLE PROMPTS

What the Browser Sent

The browser did not communicate directly with Google. It sent a small JSON request to our PHP endpoint:

{
    "prompt": "The text entered by the user",
    "csrf_token": "The current session security token"
}

Notice what is missing:

No Gemini API key
No Google endpoint
No private server configuration

The browser knows where our PHP endpoint is, but the PHP endpoint controls the Gemini connection.

The Gemini Request

After validating the browser request, PHP builds a second JSON payload for Gemini:

{
    "model": "gemini-3.5-flash",
    "store": false,
    "input": "The user's prompt"
}

Model

The model field tells the API which Gemini model should process the request.

Store

This exercise uses one independent request at a time, so it sets store to false.

Input

The input field contains the prompt submitted by the user.

The API Endpoint

PHP sends the request to:

https://generativelanguage.googleapis.com/v1/interactions

The endpoint identifies the service and API operation we want Google to perform.

PHP also sends two important HTTP headers:

Content-Type: application/json
x-goog-api-key: YOUR_PRIVATE_SERVER_KEY

The content-type header tells Google that the request body contains JSON. The API-key header authorizes the request.

The Simplified PHP Request

The actual endpoint contains validation, security, rate protection, and error handling. At its core, the request looks like this:

<?php

$apiKey = getenv('GEMINI_API_KEY');

$payload = [
    'model' => 'gemini-3.5-flash',
    'store' => false,
    'input' => $prompt
];

$curl = curl_init(
    'https://generativelanguage.googleapis.com/v1/interactions'
);

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),

    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'x-goog-api-key: ' . $apiKey
    ]
]);

$response = curl_exec($curl);

curl_close($curl);

cURL is the messenger

PHP cURL creates the HTTPS connection, attaches the headers and JSON payload, sends the request, and receives the response.

Understanding the Response

A successful Interactions API response contains general request information, usage information, and a series of execution steps.

A shortened response may resemble:

{
    "status": "completed",

    "usage": {
        "total_input_tokens": 16,
        "total_output_tokens": 72,
        "total_tokens": 88
    },

    "steps": [
        {
            "type": "model_output",

            "content": [
                {
                    "type": "text",
                    "text": "The generated answer appears here."
                }
            ]
        }
    ],

    "model": "gemini-3.5-flash"
}

Our PHP endpoint loops through the steps, finds each model_output step, and extracts its visible text.

It does not send the complete raw Gemini response to the browser. It returns only the information the interface needs:

{
    "success": true,
    "text": "The generated response",
    "model": "gemini-3.5-flash",

    "usage": {
        "input_tokens": 16,
        "output_tokens": 72,
        "total_tokens": 88
    }
}

Why We Do Not Display Every Response Step

Gemini may return several types of execution steps. Not every step is intended to become visible application content.

The application should deliberately select the output it needs instead of blindly printing the entire API response.

Do not expose raw diagnostic data automatically

Raw API responses may contain identifiers, execution details, tool information, or fields that are irrelevant to the user. Parse the response and display only what the application needs.

Why Input Validation Matters

The PHP endpoint rejects:

Empty prompts
Prompts longer than 2,000 characters
Requests without a valid session security token
Requests sent too quickly
Requests using an unsupported HTTP method

Gemini may be capable of processing much larger inputs, but that does not mean every application should accept unlimited input.

The application owner decides what is reasonable for the specific tool.

Understanding Token Usage

Gemini divides text and other content into units called tokens. API usage and model limits are measured partly through these units.

Input Tokens

Tokens used to process the prompt and any other information sent to the model.

Output Tokens

Tokens used to generate the response.

Total Tokens

The combined usage reported for the interaction.

Usage should be visible to the application

Even when users do not see token counts, the application can use this information for monitoring, credit calculations, rate controls, and cost management.

Common Errors

API Key Is Not Configured

The PHP environment does not contain a value named GEMINI_API_KEY.

Permission Denied

The key may be disabled, associated with the wrong project, or missing permission to use the selected model.

Model Not Found

Model names change over time. The model may have been retired, renamed, or unavailable to the selected project.

Rate Limit Exceeded

The Google project or this course exercise has received too many requests within a limited period.

Connection Error

The server could not establish a secure connection with the Gemini API.

Empty Output

The API completed the request but did not return a visible text result that the application could extract.

Model Names Will Change

The endpoint currently uses:

$model = 'gemini-3.5-flash';

That line is deliberately easy to find. When Google retires or replaces a model, the application can be updated without rebuilding the entire interface.

The interface is separate from the provider

The form, buttons, security, progress tracking, and output container belong to our application. Gemini is the replaceable processing service behind the endpoint.

Practical Exercise

Complete the following before marking this lesson finished:

Send the default sample prompt.
Review the generated response.
Review the input, output, and total token counts.
Run one of the supplied sample prompts.
Write and submit one original prompt.
Copy one generated result.
Explain why the browser does not need direct access to the Gemini API key.

Official Resources

Gemini API Getting Started Guide ↗

Interactions API Overview ↗

Lesson Summary

You have now sent a real server-side Gemini API request. The browser submitted a prompt to PHP, PHP attached the private API key, Gemini processed the request, and the application displayed the returned text.

This same structure forms the foundation of almost every server-connected AI application:

User Input
    ↓
Browser Interface
    ↓
Server Endpoint
    ↓
Gemini API
    ↓
Server Response Processing
    ↓
Application Output

The next section will build on this foundation by separating permanent application behavior from individual user input.