@spec cancel(String.t(), batch_opts()) :: :ok | {:error, term()}

Cancel a running batch job.

Can only cancel jobs that are in queued or running state.

Parameters

• name - Batch job name
• opts - Options

Examples

:ok = Gemini.APIs.Batches.cancel("batches/abc123")

@spec create(String.t(), create_opts()) ::
  {:ok, Gemini.Types.BatchJob.t()} | {:error, term()}

Create a new batch generation job.

Parameters

• model - Model to use for generation (e.g., "gemini-2.0-flash")
• opts - Batch creation options

Options

• :display_name - Human-readable name for the batch
• :file_name - Input file name (for Gemini API)
• :inlined_requests - Inline requests (for small batches)
• :gcs_uri - GCS input URIs (for Vertex AI)
• :bigquery_uri - BigQuery input URI (for Vertex AI)
• :generation_config - Generation configuration for all requests
• :system_instruction - System instruction for all requests
• :auth - Authentication strategy

Input File Format (JSONL)

For file-based input, each line should be a JSON object:

{"contents": [{"parts": [{"text": "First request"}]}]}
{"contents": [{"parts": [{"text": "Second request"}]}]}

Examples

# Using uploaded file
{:ok, batch} = Gemini.APIs.Batches.create("gemini-2.0-flash",
  file_name: "files/abc123",
  display_name: "My Batch"
)

# Using inline requests (small batches only)
{:ok, batch} = Gemini.APIs.Batches.create("gemini-2.0-flash",
  inlined_requests: [
    %{contents: [%{parts: [%{text: "Request 1"}]}]},
    %{contents: [%{parts: [%{text: "Request 2"}]}]}
  ],
  display_name: "Small Batch"
)

# With generation config
{:ok, batch} = Gemini.APIs.Batches.create("gemini-2.0-flash",
  file_name: "files/abc123",
  generation_config: %{
    temperature: 0.7,
    maxOutputTokens: 1000
  }
)

@spec create_embeddings(String.t(), create_opts()) ::
  {:ok, Gemini.Types.BatchJob.t()} | {:error, term()}

Create a new batch embedding job.

Similar to create/2 but for embedding requests.

Parameters

• model - Embedding model to use
• opts - Batch creation options

Input File Format (JSONL)

For embeddings, each line should contain text to embed:

{"content": {"parts": [{"text": "Text to embed"}]}}
{"content": {"parts": [{"text": "Another text"}]}}

Examples

{:ok, batch} = Gemini.APIs.Batches.create_embeddings("text-embedding-004",
  file_name: "files/embeddings-input",
  display_name: "Embedding Batch"
)

@spec delete(String.t(), batch_opts()) :: :ok | {:error, term()}

Delete a batch job.

Typically used to clean up completed jobs.

Parameters

• name - Batch job name
• opts - Options

Examples

:ok = Gemini.APIs.Batches.delete("batches/abc123")

@spec get(String.t(), batch_opts()) ::
  {:ok, Gemini.Types.BatchJob.t()} | {:error, term()}

Get the status of a batch job.

Parameters

• name - Batch job name (e.g., "batches/abc123")
• opts - Options

Examples

{:ok, batch} = Gemini.APIs.Batches.get("batches/abc123")
IO.puts("State: #{batch.state}")

if batch.completion_stats do
  IO.puts("Progress: #{batch.completion_stats.success_count}/#{batch.completion_stats.total_count}")
end

@spec get_responses(Gemini.Types.BatchJob.t()) :: {:ok, [map()]} | {:error, term()}

Get inlined responses from a completed batch job.

Only works for batches with inline response output.

Parameters

• batch - Completed BatchJob with inlined responses
• opts - Options

Examples

{:ok, batch} = Gemini.APIs.Batches.get("batches/abc123")
if BatchJob.succeeded?(batch) do
  {:ok, responses} = Gemini.APIs.Batches.get_responses(batch)
  Enum.each(responses, &process_response/1)
end

@spec list(list_opts()) ::
  {:ok, Gemini.Types.ListBatchJobsResponse.t()} | {:error, term()}

List batch jobs.

Parameters

• opts - List options

Options

• :page_size - Number of jobs per page (default: 100)
• :page_token - Token from previous response for pagination
• :filter - Filter string
• :auth - Authentication strategy

Examples

{:ok, response} = Gemini.APIs.Batches.list()

Enum.each(response.batch_jobs, fn job ->
  IO.puts("#{job.name}: #{job.state}")
end)

# With pagination
{:ok, response} = Gemini.APIs.Batches.list(page_size: 10)
if ListBatchJobsResponse.has_more_pages?(response) do
  {:ok, page2} = Gemini.APIs.Batches.list(page_token: response.next_page_token)
end

@spec list_all(list_opts()) :: {:ok, [Gemini.Types.BatchJob.t()]} | {:error, term()}

List all batch jobs across all pages.

Automatically handles pagination.

Examples

{:ok, all_jobs} = Gemini.APIs.Batches.list_all()
running = Enum.filter(all_jobs, &BatchJob.running?/1)

@spec wait(String.t(), wait_opts()) ::
  {:ok, Gemini.Types.BatchJob.t()} | {:error, term()}

Wait for a batch job to complete.

Polls the batch status until it reaches a terminal state (succeeded, failed, etc.) or the timeout is reached.

Parameters

• name - Batch job name
• opts - Wait options

Options

• :poll_interval - Milliseconds between status checks (default: 30000)
• :timeout - Maximum wait time in milliseconds (default: 3600000 = 1 hour)
• :on_progress - Callback for status updates fn(BatchJob.t()) -> any()

Examples

{:ok, completed} = Gemini.APIs.Batches.wait("batches/abc123",
  poll_interval: 60_000,   # Check every minute
  timeout: 7_200_000,      # Wait up to 2 hours
  on_progress: fn batch ->
    if progress = BatchJob.get_progress(batch) do
      IO.puts("Progress: #{Float.round(progress, 1)}%")
    end
  end
)

cond do
  BatchJob.succeeded?(completed) ->
    IO.puts("Success!")
  BatchJob.failed?(completed) ->
    IO.puts("Failed: #{completed.error.message}")
end