0
# Types Reference
1

2
Common types and data models used throughout the SDK including Content, Part, Schema, configurations, and media types.
3

4
## Core Imports
5

6
```java
7
import com.google.genai.types.Content;
8
import com.google.genai.types.Part;
9
import com.google.genai.types.Blob;
10
import com.google.genai.types.FileData;
11
import com.google.genai.types.Image;
12
import com.google.genai.types.Video;
13
import com.google.genai.types.Schema;
14
import com.google.genai.types.SafetySetting;
15
import com.google.genai.types.Tool;
16
import com.google.genai.types.FunctionDeclaration;
17
import com.google.genai.types.FunctionCall;
18
import com.google.genai.types.FunctionResponse;
19
```
20

21
## Content Types
22

23
### Content
24

25
```java { .api }
26
package com.google.genai.types;
27

28
public final class Content {
29
  public static Content fromParts(Part... parts);
30
  public static Content fromParts(List<Part> parts);
31
  public static Builder builder();
32

33
  public Optional<List<Part>> parts();
34
  public Optional<String> role();
35

36
  public Builder toBuilder();
37
}
38
```
39

40
**Usage:**
41

42
```java
43
// Simple text content
44
Content content = Content.fromParts(Part.fromText("Hello"));
45

46
// With role
47
Content content = Content.builder()
48
    .parts(ImmutableList.of(Part.fromText("Hello")))
49
    .role("user")
50
    .build();
51

52
// Multimodal content
53
Content content = Content.fromParts(
54
    Part.fromText("Describe this image"),
55
    Part.fromImage(image)
56
);
57
```
58

59
### Part
60

61
```java { .api }
62
package com.google.genai.types;
63

64
public final class Part {
65
  // Factory methods
66
  public static Part fromText(String text);
67
  public static Part fromImage(Image image);
68
  public static Part fromVideo(Video video);
69
  public static Part fromFileData(FileData fileData);
70
  public static Part fromFunctionCall(FunctionCall functionCall);
71
  public static Part fromFunctionResponse(FunctionResponse functionResponse);
72
  public static Part fromUri(String uri, String mimeType);
73

74
  public static Builder builder();
75

76
  // Fields (mutually exclusive)
77
  public Optional<String> text();
78
  public Optional<Blob> inlineData();
79
  public Optional<FileData> fileData();
80
  public Optional<FunctionCall> functionCall();
81
  public Optional<FunctionResponse> functionResponse();
82
  public Optional<ExecutableCode> executableCode();
83
  public Optional<CodeExecutionResult> codeExecutionResult();
84
  public Optional<String> thought();
85
}
86
```
87

88
**Usage:**
89

90
```java
91
// Text part
92
Part textPart = Part.fromText("Hello world");
93

94
// Image part
95
Part imagePart = Part.fromImage(image);
96

97
// File reference part
98
Part filePart = Part.fromUri("gs://bucket/file.pdf", "application/pdf");
99

100
// Function call part
101
Part functionPart = Part.fromFunctionCall(functionCall);
102
```
103

104
### Blob
105

106
```java { .api }
107
package com.google.genai.types;
108

109
public final class Blob {
110
  public static Builder builder();
111

112
  public Optional<String> data();
113
  public Optional<String> mimeType();
114
  public Optional<String> displayName();
115
}
116
```
117

118
**Usage:**
119

120
```java
121
import java.util.Base64;
122

123
byte[] imageBytes = Files.readAllBytes(Paths.get("image.jpg"));
124
String base64Data = Base64.getEncoder().encodeToString(imageBytes);
125

126
Blob blob = Blob.builder()
127
    .data(base64Data)
128
    .mimeType("image/jpeg")
129
    .build();
130

131
Part part = Part.builder()
132
    .inlineData(blob)
133
    .build();
134
```
135

136
### FileData
137

138
```java { .api }
139
package com.google.genai.types;
140

141
public final class FileData {
142
  public static Builder builder();
143

144
  public Optional<String> fileUri();
145
  public Optional<String> mimeType();
146
  public Optional<String> displayName();
147
}
148
```
149

150
**Usage:**
151

152
```java
153
FileData fileData = FileData.builder()
154
    .fileUri("gs://bucket/document.pdf")
155
    .mimeType("application/pdf")
156
    .displayName("My Document")
157
    .build();
158

159
Part part = Part.fromFileData(fileData);
160
```
161

162
## Media Types
163

164
### Image
165

166
```java { .api }
167
package com.google.genai.types;
168

169
public final class Image {
170
  public static Image fromFile(String filePath);
171
  public static Builder builder();
172

173
  public Optional<String> imageUri();
174
  public Optional<byte[]> imageBytes();
175
  public Optional<String> gcsUri();
176
  public Optional<String> mimeType();
177
}
178
```
179

180
**Usage:**
181

182
```java
183
// From file
184
Image image = Image.fromFile("path/to/image.jpg");
185

186
// From URI
187
Image image = Image.builder()
188
    .imageUri("https://example.com/image.jpg")
189
    .mimeType("image/jpeg")
190
    .build();
191

192
// From GCS
193
Image image = Image.builder()
194
    .gcsUri("gs://bucket/image.jpg")
195
    .mimeType("image/jpeg")
196
    .build();
197

198
// From bytes
199
Image image = Image.builder()
200
    .imageBytes(imageBytes)
201
    .mimeType("image/png")
202
    .build();
203
```
204

205
### Video
206

207
```java { .api }
208
package com.google.genai.types;
209

210
public final class Video {
211
  public static Builder builder();
212

213
  public Optional<String> videoUri();
214
  public Optional<byte[]> videoBytes();
215
  public Optional<String> gcsUri();
216
  public Optional<String> mimeType();
217
}
218
```
219

220
**Usage:**
221

222
```java
223
Video video = Video.builder()
224
    .gcsUri("gs://bucket/video.mp4")
225
    .mimeType("video/mp4")
226
    .build();
227

228
Video video2 = Video.builder()
229
    .videoUri("https://example.com/video.mp4")
230
    .mimeType("video/mp4")
231
    .build();
232
```
233

234
## Schema Types
235

236
### Schema
237

238
```java { .api }
239
package com.google.genai.types;
240

241
public final class Schema {
242
  public static Builder builder();
243

244
  public Optional<String> type();
245
  public Optional<String> format();
246
  public Optional<String> description();
247
  public Optional<Boolean> nullable();
248
  public Optional<List<String>> enum_();
249
  public Optional<Map<String, Schema>> properties();
250
  public Optional<List<String>> required();
251
  public Optional<Schema> items();
252
  public Optional<Long> minItems();
253
  public Optional<Long> maxItems();
254
  public Optional<Double> minimum();
255
  public Optional<Double> maximum();
256
}
257
```
258

259
**Type Constants:**
260

261
```java { .api }
262
package com.google.genai.types;
263

264
public final class Type {
265
  public static final class Known {
266
    public static final String STRING = "STRING";
267
    public static final String NUMBER = "NUMBER";
268
    public static final String INTEGER = "INTEGER";
269
    public static final String BOOLEAN = "BOOLEAN";
270
    public static final String ARRAY = "ARRAY";
271
    public static final String OBJECT = "OBJECT";
272
  }
273
}
274
```
275

276
**Usage:**
277

278
```java
279
import com.google.common.collect.ImmutableMap;
280
import com.google.common.collect.ImmutableList;
281

282
// Simple string schema
283
Schema schema = Schema.builder()
284
    .type(Type.Known.STRING)
285
    .description("A person's name")
286
    .build();
287

288
// Object schema
289
Schema personSchema = Schema.builder()
290
    .type(Type.Known.OBJECT)
291
    .properties(ImmutableMap.of(
292
        "name", Schema.builder()
293
            .type(Type.Known.STRING)
294
            .build(),
295
        "age", Schema.builder()
296
            .type(Type.Known.INTEGER)
297
            .minimum(0.0)
298
            .build()
299
    ))
300
    .required(ImmutableList.of("name"))
301
    .build();
302

303
// Array schema
304
Schema arraySchema = Schema.builder()
305
    .type(Type.Known.ARRAY)
306
    .items(Schema.builder()
307
        .type(Type.Known.STRING)
308
        .build())
309
    .minItems(1L)
310
    .maxItems(10L)
311
    .build();
312

313
// Enum schema
314
Schema colorSchema = Schema.builder()
315
    .type(Type.Known.STRING)
316
    .enum_(ImmutableList.of("red", "green", "blue"))
317
    .build();
318
```
319

320
## Safety Types
321

322
### SafetySetting
323

324
```java { .api }
325
package com.google.genai.types;
326

327
public final class SafetySetting {
328
  public static Builder builder();
329

330
  public Optional<String> category();
331
  public Optional<String> threshold();
332
  public Optional<String> method();
333
}
334
```
335

336
**Categories:**
337

338
```java { .api }
339
package com.google.genai.types;
340

341
public final class HarmCategory {
342
  public static final class Known {
343
    public static final String HARM_CATEGORY_UNSPECIFIED = "HARM_CATEGORY_UNSPECIFIED";
344
    public static final String HARM_CATEGORY_HATE_SPEECH = "HARM_CATEGORY_HATE_SPEECH";
345
    public static final String HARM_CATEGORY_DANGEROUS_CONTENT = "HARM_CATEGORY_DANGEROUS_CONTENT";
346
    public static final String HARM_CATEGORY_HARASSMENT = "HARM_CATEGORY_HARASSMENT";
347
    public static final String HARM_CATEGORY_SEXUALLY_EXPLICIT = "HARM_CATEGORY_SEXUALLY_EXPLICIT";
348
  }
349
}
350
```
351

352
**Thresholds:**
353

354
```java { .api }
355
package com.google.genai.types;
356

357
public final class HarmBlockThreshold {
358
  public static final class Known {
359
    public static final String HARM_BLOCK_THRESHOLD_UNSPECIFIED = "HARM_BLOCK_THRESHOLD_UNSPECIFIED";
360
    public static final String BLOCK_LOW_AND_ABOVE = "BLOCK_LOW_AND_ABOVE";
361
    public static final String BLOCK_MEDIUM_AND_ABOVE = "BLOCK_MEDIUM_AND_ABOVE";
362
    public static final String BLOCK_ONLY_HIGH = "BLOCK_ONLY_HIGH";
363
    public static final String BLOCK_NONE = "BLOCK_NONE";
364
    public static final String OFF = "OFF";
365
  }
366
}
367
```
368

369
**Usage:**
370

371
```java
372
SafetySetting setting = SafetySetting.builder()
373
    .category(HarmCategory.Known.HARM_CATEGORY_HATE_SPEECH)
374
    .threshold(HarmBlockThreshold.Known.BLOCK_MEDIUM_AND_ABOVE)
375
    .build();
376
```
377

378
### SafetyRating
379

380
```java { .api }
381
package com.google.genai.types;
382

383
public final class SafetyRating {
384
  public Optional<String> category();
385
  public Optional<String> probability();
386
  public Optional<Boolean> blocked();
387
  public Optional<Double> probabilityScore();
388
  public Optional<String> severity();
389
  public Optional<Double> severityScore();
390
}
391
```
392

393
## Tool Types
394

395
### Tool
396

397
```java { .api }
398
package com.google.genai.types;
399

400
public final class Tool {
401
  public static Builder builder();
402

403
  public Optional<List<FunctionDeclaration>> functionDeclarations();
404
  public Optional<GoogleSearchRetrieval> googleSearchRetrieval();
405
  public Optional<GoogleSearch> googleSearch();
406
  public Optional<GoogleMaps> googleMaps();
407
  public Optional<CodeExecution> codeExecution();
408
  public Optional<FileSearch> fileSearch();
409
  public Optional<ComputerUse> computerUse();
410
  public Optional<Retrieval> retrieval();
411
  public Optional<UrlContext> urlContext();
412
}
413
```
414

415
**Usage:**
416

417
```java
418
// Function tool
419
Tool functionTool = Tool.builder()
420
    .functionDeclarations(ImmutableList.of(functionDeclaration))
421
    .build();
422

423
// Google Search tool
424
Tool searchTool = Tool.builder()
425
    .googleSearch(GoogleSearch.builder().build())
426
    .build();
427

428
// Code execution tool
429
Tool codeExecTool = Tool.builder()
430
    .codeExecution(CodeExecution.builder().build())
431
    .build();
432
```
433

434
### FunctionDeclaration
435

436
```java { .api }
437
package com.google.genai.types;
438

439
public final class FunctionDeclaration {
440
  public static Builder builder();
441

442
  public Optional<String> name();
443
  public Optional<String> description();
444
  public Optional<Schema> parameters();
445
}
446
```
447

448
**Usage:**
449

450
```java
451
FunctionDeclaration function = FunctionDeclaration.builder()
452
    .name("getCurrentWeather")
453
    .description("Get the current weather in a location")
454
    .parameters(Schema.builder()
455
        .type(Type.Known.OBJECT)
456
        .properties(ImmutableMap.of(
457
            "location", Schema.builder()
458
                .type(Type.Known.STRING)
459
                .description("City name")
460
                .build(),
461
            "unit", Schema.builder()
462
                .type(Type.Known.STRING)
463
                .enum_(ImmutableList.of("celsius", "fahrenheit"))
464
                .build()
465
        ))
466
        .required(ImmutableList.of("location"))
467
        .build())
468
    .build();
469
```
470

471
### FunctionCall
472

473
```java { .api }
474
package com.google.genai.types;
475

476
public final class FunctionCall {
477
  public static Builder builder();
478

479
  public Optional<String> name();
480
  public Optional<JsonNode> args();
481
  public Optional<String> id();
482
}
483
```
484

485
### FunctionResponse
486

487
```java { .api }
488
package com.google.genai.types;
489

490
public final class FunctionResponse {
491
  public static Builder builder();
492

493
  public Optional<String> name();
494
  public Optional<JsonNode> response();
495
  public Optional<String> id();
496
}
497
```
498

499
**Usage:**
500

501
```java
502
// Process function call from model
503
Part part = response.part();
504
part.functionCall().ifPresent(call -> {
505
    String functionName = call.name().orElse("");
506
    JsonNode args = call.args().orElse(null);
507

508
    // Execute function
509
    Object result = executeFunction(functionName, args);
510

511
    // Create response
512
    FunctionResponse functionResponse = FunctionResponse.builder()
513
        .name(functionName)
514
        .response(objectMapper.valueToTree(result))
515
        .id(call.id().orElse(null))
516
        .build();
517

518
    // Send back to model
519
    Content responseContent = Content.fromParts(
520
        Part.fromFunctionResponse(functionResponse)
521
    );
522
});
523
```
524

525
## Constant Types
526

527
### FinishReason
528

529
```java { .api }
530
package com.google.genai.types;
531

532
public final class FinishReason {
533
  public static final class Known {
534
    public static final String FINISH_REASON_UNSPECIFIED = "FINISH_REASON_UNSPECIFIED";
535
    public static final String STOP = "STOP";
536
    public static final String MAX_TOKENS = "MAX_TOKENS";
537
    public static final String SAFETY = "SAFETY";
538
    public static final String RECITATION = "RECITATION";
539
    public static final String OTHER = "OTHER";
540
    public static final String BLOCKLIST = "BLOCKLIST";
541
    public static final String PROHIBITED_CONTENT = "PROHIBITED_CONTENT";
542
    public static final String SPII = "SPII";
543
    public static final String MALFORMED_FUNCTION_CALL = "MALFORMED_FUNCTION_CALL";
544
  }
545
}
546
```
547

548
### BlockedReason
549

550
```java { .api }
551
package com.google.genai.types;
552

553
public final class BlockedReason {
554
  public static final class Known {
555
    public static final String BLOCKED_REASON_UNSPECIFIED = "BLOCKED_REASON_UNSPECIFIED";
556
    public static final String SAFETY = "SAFETY";
557
    public static final String OTHER = "OTHER";
558
    public static final String BLOCKLIST = "BLOCKLIST";
559
    public static final String PROHIBITED_CONTENT = "PROHIBITED_CONTENT";
560
  }
561
}
562
```
563

564
### FunctionCallingMode
565

566
```java { .api }
567
package com.google.genai.types;
568

569
public final class FunctionCallingMode {
570
  public static final class Known {
571
    public static final String MODE_UNSPECIFIED = "MODE_UNSPECIFIED";
572
    public static final String AUTO = "AUTO";
573
    public static final String ANY = "ANY";
574
    public static final String NONE = "NONE";
575
  }
576
}
577
```
578

579
## HTTP Types
580

581
### HttpOptions
582

583
```java { .api }
584
package com.google.genai.types;
585

586
public final class HttpOptions {
587
  public static Builder builder();
588

589
  public Optional<String> baseUrl();
590
  public Optional<String> apiVersion();
591
  public Optional<Integer> timeout();
592
  public Optional<Map<String, String>> headers();
593
  public Optional<JsonNode> extraBody();
594
  public Optional<JsonNode> extraQuery();
595
  public Optional<HttpRetryOptions> retryOptions();
596
}
597
```
598

599
### HttpResponse
600

601
```java { .api }
602
package com.google.genai.types;
603

604
public final class HttpResponse {
605
  public static Builder builder();
606

607
  public Optional<Map<String, String>> headers();
608
  public Optional<String> body();
609
}
610
```
611

612
## Pagination Types
613

614
### Pager
615

616
```java { .api }
617
package com.google.genai;
618

619
public final class Pager<T> implements Iterable<T> {
620
  public ImmutableList<T> page();
621
  public ImmutableList<T> nextPage();
622
  public Iterator<T> iterator();
623
  public String name();
624
  public int pageSize();
625
  public int size();
626
  public Optional<HttpResponse> sdkHttpResponse();
627
}
628
```
629

630
### AsyncPager
631

632
```java { .api }
633
package com.google.genai;
634

635
public final class AsyncPager<T> {
636
  public CompletableFuture<ImmutableList<T>> page();
637
  public CompletableFuture<ImmutableList<T>> nextPage();
638
  public CompletableFuture<Void> forEach(Consumer<? super T> itemAction);
639
  public CompletableFuture<String> name();
640
  public CompletableFuture<Integer> pageSize();
641
  public CompletableFuture<Integer> size();
642
  public CompletableFuture<Optional<HttpResponse>> sdkHttpResponse();
643
}
644
```
645

646
## Builder Pattern
647

648
All configuration and data types use the builder pattern:
649

650
```java
651
// Create builder
652
Content.Builder builder = Content.builder();
653

654
// Set fields
655
builder.parts(ImmutableList.of(Part.fromText("Hello")));
656
builder.role("user");
657

658
// Build immutable instance
659
Content content = builder.build();
660

661
// Modify existing instance
662
Content modified = content.toBuilder()
663
    .role("model")
664
    .build();
665
```
666

667
## Optional Usage
668

669
Most fields use `Optional<T>`:
670

671
```java
672
Content content = getContent();
673

674
// Check if present
675
if (content.role().isPresent()) {
676
    String role = content.role().get();
677
}
678

679
// Or use orElse
680
String role = content.role().orElse("user");
681

682
// Or use ifPresent
683
content.role().ifPresent(r -> {
684
    System.out.println("Role: " + r);
685
});
686

687
// Or use map
688
String upperRole = content.role()
689
    .map(String::toUpperCase)
690
    .orElse("UNKNOWN");
691
```
692

693
## Immutability
694

695
All types are immutable after creation:
696

697
```java
698
Content content = Content.builder()
699
    .role("user")
700
    .build();
701

702
// Cannot modify - need to create new instance
703
Content newContent = content.toBuilder()
704
    .role("model")
705
    .build();
706
```
707