Skip to contents

Get started with artgemini

Source: vignettes/artgemini.qmd

Introduction

artgemini provides a streamlined interface to Google’s Gemini API for R users. The package is designed to support two primary use cases:

  1. Interactive chat workflows - Multi-turn conversations with streaming support via {ellmer} Chat objects
  2. Single-turn structured output - Low-level API for pipeline tasks with JSON schemas

This guide walks you through the essential workflows to get you started with artgemini.

Installation 

pak::pkg_install("artalytics/artgemini")
library(artgemini)

Configuration

Before using artgemini, you need to configure your Google Gemini API key. Set the following environment variable:

# API key should be set in .Renviron before running
Sys.setenv(ART_GEMINI_KEY = ...)
# Verify your configuration with a health check:
artgemini_health_check()

Interactive Chat

The gemini_chat() function returns an ellmer Chat object for multi-turn conversations.

# Create chat object
chat <- gemini_chat()

# Send messages
chat$chat("Explain the difference between impressionism and expressionism in art.")

# Multi-turn conversation
chat$chat("Which movement came first?")
chat$chat("Name 3 famous impressionist painters.")

System Prompts

Set behavioral context with system prompts:

chat <- gemini_chat(sys_prompt = "You are an art historian. Be concise.")
chat$chat("What is Baroque?")

Temperature Control

Control output randomness with the temp parameter:

# Deterministic output
chat_det <- gemini_chat(temp = 0)
chat_det$chat("List 5 common art styles as a comma-separated list.")

# Creative output
chat_creative <- gemini_chat(temp = 1.5)
chat_creative$chat("Write a 50 word story about an artist.")

Model Selection

Override the default model with the ml parameter:

# Fast responses
chat_fast <- gemini_chat(ml = "gemini-2.5-flash")
chat_fast$chat("Quick question")

# High-quality analysis
chat_pro <- gemini_chat(ml = "gemini-2.5-pro")
chat_pro$chat("Complex analysis task")

Single-Turn Structured Output

For pipeline tasks requiring structured JSON output, use gemini_generate():

# Build contents manually
contents <- list(
  list(
    role = "user",
    parts = list(list(text = "List 3 art styles"))
  )
)

resp <- gemini_generate(
  contents = contents,
  temp = 0,
  resp_fmt = list(type = "json_object")
)

# Parse JSON
jsonlite::fromJSON(resp)

Vision: Describing Images

Use gemini_describe_image() for image analysis:

# Default prompt
gemini_describe_image(img_path, temp = 0.7)

# Custom analysis prompt
gemini_describe_image(
  img_path,
  prompt = "Describe the color palette and composition.",
  temp = 0
)

Tools & Function Calling

Enhance Gemini with tools for grounded search and code execution:

# Google Search grounding
gemini_with_tools(
  "What are the latest trends in digital art for 2025?",
  tools = list(tool_google_search())
)

# Code execution
gemini_with_tools(
  "Calculate the Fibonacci sequence up to the 20th term.",
  tools = list(tool_code_execution())
)

Next Steps

For questions and issues, visit the GitHub repository.