BYTESLIP ← Back
Knowledge Base // Tutorial 113

Call the Gemini API from Termux with curl and jq

Difficulty: Medium ~20 min Termux · Gemini API

The Gemini app is not the only way to use Gemini on a tablet. Google’s Gemini API takes a plain HTTPS request, so Termux can ask it questions with curl and read the answer with jq — no Python SDK, no browser. This guide stores the key so it stays out of your shell history and builds a small gem command you can pipe text into.

Termux to Gemini API pipeline Four tiles: Termux, curl, Gemini API, and jq. TERMUX CURL GEMINI API JQ
Checklist // Before You Start

What You Need

This is the developer API, not the Gemini app. It has its own key, its own quotas, and its own terms. Google’s terms say that on the free (unpaid) tier, what you send and what comes back may be used to improve Google products, and human reviewers may read it. Do not send passwords, medical records, or anything you would not post publicly. The model name and request format below come from Google’s Gemini API quickstart as of November 2026; if Google renames the model, change one variable.

Walkthrough // Steps 01–06

Install, Store the Key, Then Ask

Works the same on a phone or a tablet. Everything happens in Termux except creating the key, which happens in a browser.

  1. Step 1: Install curl and jq

    Update Termux and install the two tools. curl sends the request; jq builds safe JSON and pulls the answer out of the reply.

    pkg update
    pkg install curl jq
  2. Step 2: Create a Gemini API key in Google AI Studio

    Open aistudio.google.com/apikey in your browser and sign in. Google’s quickstart says AI Studio creates a project and key for new users automatically; copy it from the API keys page, or tap Create API key for a new one.

    Google’s API key page says that starting May 28, 2026, new keys made in AI Studio are authorization keys restricted to the Gemini API. The API also rejects unrestricted older standard keys. If an old key from another project fails, make a new one in AI Studio.

  3. Step 3: Store the key so it never shows on screen

    Google recommends keeping the key in the GEMINI_API_KEY environment variable. These commands read it without echoing, save it to a private file, and load it every time Termux opens. Paste the key when asked; nothing appears while you paste.

    read -rs -p "Paste key: " k; echo
    printf 'export GEMINI_API_KEY=%s\n' "$k" > ~/.gemini_key; unset k
    chmod 600 ~/.gemini_key
    echo '[ -f ~/.gemini_key ] && . ~/.gemini_key' >> ~/.bashrc
    . ~/.bashrc
    echo ${#GEMINI_API_KEY}

    The last line prints only the key’s length, so you can confirm it loaded without showing it. Because the key never appears in a command line, it stays out of ~/.bash_history.

  4. Step 4: Send your first request

    This is the REST example from Google’s quickstart, unchanged except for the prompt. It prints the full JSON reply.

    curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
      -H "x-goog-api-key: $GEMINI_API_KEY" \
      -H 'Content-Type: application/json' \
      -H "Api-Revision: 2026-05-20" \
      -d '{
        "model": "gemini-4-hydrogen",
        "input": "In one sentence, what is a lava tube?"
      }'

    The answer is inside steps, in the item whose type is model_output. Other steps, like thought, hold no readable text.

  5. Step 5: Make a reusable gem command

    Save this as ~/gem.sh (with a text editor such as nano ~/gem.sh; install it with pkg install nano if needed), then add [ -f ~/gem.sh ] && . ~/gem.sh to ~/.bashrc. It uses jq --arg so quotes and new lines in your prompt cannot break the JSON, and it prints only the answer text or a one-line error.

    # ~/gem.sh — ask the Gemini API from Termux (Byteslip)
    gem() {
      if [ -z "$GEMINI_API_KEY" ]; then
        echo "GEMINI_API_KEY is not set" >&2; return 1
      fi
      local prompt="$*"
      [ -z "$prompt" ] && prompt="$(cat)"
      local body
      body=$(jq -n --arg m "${GEMINI_MODEL:-gemini-4-hydrogen}" --arg p "$prompt" '{model:$m, input:$p}')
      curl -sS -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
        -H "x-goog-api-key: $GEMINI_API_KEY" \
        -H 'Content-Type: application/json' \
        -H "Api-Revision: 2026-05-20" \
        -d "$body" |
      jq -r '(if type=="array" then .[0] else . end) | if .error then "Error \(.error.code): \(.error.message)"
             else [.steps[]? | select(.type=="model_output") | .content[]? | select(.type=="text") | .text] | join("\n") end'
    }

    Use it with an argument, or pipe text in:

    gem 'Explain chmod 600 in one sentence.'
    { echo 'Summarize these notes in 3 bullets:'; cat ~/notes.txt; } | gem
    GEMINI_MODEL=some-other-model gem 'hello'

    Byteslip tested the function’s JSON building, answer extraction, and error handling in bash with curl 8 and jq 1.7 against Google’s documented reply and the live endpoint’s error replies.

  6. Step 6: Read the common errors

    Error 400: API key not valid — the key is mistyped, deleted, or an unrestricted old key. Re-run Step 3 with a fresh AI Studio key.

    Error 403: Permission denied — usually no key was sent at all. Check that echo ${#GEMINI_API_KEY} prints a number above zero in this Termux session.

    Error 429 — you hit a rate limit. Google measures requests per minute, tokens per minute, and requests per day, per project rather than per key, and says the daily quota resets at midnight Pacific time. In Hawaiʻi that is 10:00 PM HST in winter and 9:00 PM HST while the mainland is on daylight time. Check your exact limits in AI Studio.

    An error that names the model — Google may have retired or renamed it. Pick a current name from the quickstart and set GEMINI_MODEL.

Pro Tip

Treat the key like a password

Keep Reading
Sources // Verified

Official docs

API key, environment variable, REST request, response format, and model name: Gemini API quickstart. Auth keys from May 28, 2026, rejection of unrestricted standard keys, and key safety rules: Using Gemini API keys. RPM, TPM, RPD, per-project limits, and the midnight Pacific reset: Rate limits. Age 18+, unpaid-tier data use, and human review: Gemini API Additional Terms of Service.

← All Tutorials Byteslip Apps