Skip to contents

Candidate Responses from Gemini

Source: vignettes/candidates.qmd

Configure environment variables per this README section.

Objective

Show the full array of candidates Gemini returns for one request, so you can see what (if anything) is lost when we only use the first candidate’s text.

Send a Request for Multiple Candidates

We ask for two candidates by setting generationConfig.candidateCount = 2.

Important: Use gemini-2.5-flash or gemini-2.5-pro for multi-candidate requests. Gemini 3 preview models do not support candidateCount > 1 and will return HTTP 400.

req_body <- list(
  contents = list(
    list(
      role = "user",
      parts = list(list(text = "Give me two short taglines for an art catalogue."))
    )
  ),
  generationConfig = list(
    temperature = 0.2,
    candidateCount = 2
  )
)

cfg <- artgemini:::.get_gemini_cfg()
ml <- "gemini-2.5-flash"
url <- paste0(cfg$base_url, "/models/", ml, ":generateContent")

resp <- httr2::request(url) |>
  httr2::req_headers("x-goog-api-key" = cfg$api_key) |>
  httr2::req_body_json(req_body, auto_unbox = TRUE) |>
  httr2::req_timeout(15) |>
  httr2::req_perform()

status <- httr2::resp_status(resp)
stopifnot(status >= 200, status < 300)

parsed <- httr2::resp_body_json(resp, simplifyVector = FALSE)
length(parsed$candidates)
[1] 2

Inspect All Candidates 

parsed$candidates |>
  vapply(function(x) x$content$parts[[1]]$text, character(1))
[1] "Here are two short taglines for an art catalogue:\n\n1.  **Art Unveiled. Inspiration Within.**\n2.  **Curated Visions. Your Guide to Discovery.**"
[2] "Here are two short taglines for an art catalogue:\n\n1.  **Visions Unveiled.**\n2.  **Curated Beauty.**"

Compare to artgemini Default Behavior

artgemini::gemini_chat() returns only the first candidate text. Here’s what you get via the high-level wrapper versus the full set above:

{r compare, results='hide'}# Use gemini_generate() for single-turn with full controlgemini_generate( contents = list(list(role = "user", parts = list(list(text = "Give me two short taglines for an art catalogue.")))), temp = 0.2, timeout = 15, ml = "gemini-2.5-flash")

What is Lost by Keeping Only the First Candidate?

  • If candidateCount > 1, the additional candidates can contain alternative phrasings. In the example above, we see two distinct variants.
  • If candidateCount is left at the API default (1), nothing is lost.

Takeaways

  1. Default behavior: artgemini uses only the first candidate for simplicity and determinism
  2. For alternatives: Call the API directly with candidateCount and parse the candidates array yourself (as shown above)
  3. Model compatibility: Use gemini-2.5-flash or gemini-2.5-pro for multi-candidate requests; Gemini 3 models return HTTP 400
  4. Production recommendation: Stick to the first candidate for consistent, reproducible outputs; use multiple candidates only when you explicitly need phrasing alternatives