{"id":39704743,"url":"https://github.com/glaforge/gemini-interactions-api-sdk","last_synced_at":"2026-05-02T14:02:23.143Z","repository":{"id":328682830,"uuid":"1116301656","full_name":"glaforge/gemini-interactions-api-sdk","owner":"glaforge","description":"Java implementation of the Gemini Interactions API","archived":false,"fork":false,"pushed_at":"2026-04-08T09:10:26.000Z","size":200,"stargazers_count":17,"open_issues_count":1,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T10:20:24.140Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/glaforge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-14T15:44:25.000Z","updated_at":"2026-04-08T09:10:30.000Z","dependencies_parsed_at":"2025-12-17T09:03:35.665Z","dependency_job_id":null,"html_url":"https://github.com/glaforge/gemini-interactions-api-sdk","commit_stats":null,"previous_names":["glaforge/gemini-interactions-api-sdk"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/glaforge/gemini-interactions-api-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glaforge%2Fgemini-interactions-api-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glaforge%2Fgemini-interactions-api-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glaforge%2Fgemini-interactions-api-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glaforge%2Fgemini-interactions-api-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glaforge","download_url":"https://codeload.github.com/glaforge/gemini-interactions-api-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glaforge%2Fgemini-interactions-api-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32536582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-18T10:31:38.940Z","updated_at":"2026-05-02T14:02:23.129Z","avatar_url":"https://github.com/glaforge.png","language":"Java","funding_links":[],"categories":["人工智能"],"sub_categories":["LLM客户端"],"readme":"# Gemini Interactions SDK for Java\n\nA modern Java SDK for the Google Gemini Interactions API.\n\n## Features\n- **Modern Java**: Built with Java 17+, utilizing Records, Sealed Interfaces, and pattern matching.\n- **Easy to Use**: Fluent Builder APIs for constructing requests.\n- **Multimodal**: Native support for Text, Image, and Function Calling.\n- **Lightweight**: Minimal dependencies (Jackson, Java Standard Library).\n\n## Installation\n\nAdd the dependency to your `pom.xml`:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.glaforge\u003c/groupId\u003e\n    \u003cartifactId\u003egemini-interactions-api-sdk\u003c/artifactId\u003e\n    \u003cversion\u003e0.8.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Usage\n\n### Initialization\n```java\nimport io.github.glaforge.gemini.interactions.GeminiInteractionsClient;\nimport io.github.glaforge.gemini.interactions.model.*;\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;\n\nGeminiInteractionsClient client = GeminiInteractionsClient.builder()\n    .apiKey(System.getenv(\"GEMINI_API_KEY\"))\n    .build();\n```\n\n### Simple Text Interaction\n```java\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\"Why is the sky blue?\")\n    .build();\n\nInteraction response = client.create(request);\nSystem.out.println(response.outputs().get(0));\n```\n\n### Streaming Response\n```java\nimport io.github.glaforge.gemini.interactions.model.Events.ContentDelta;\nimport io.github.glaforge.gemini.interactions.model.Events.TextDelta;\n\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\"Why is the sky blue?\")\n    .stream(true)\n    .build();\n\nclient.stream(request).forEach(event -\u003e {\n    if (event instanceof ContentDelta delta) {\n        if (delta.delta() instanceof TextDelta textPart) {\n            System.out.print(textPart.text());\n        }\n    }\n});\n```\n\n### Multi-turn Conversation\n```java\nimport io.github.glaforge.gemini.interactions.model.Interaction.Turn;\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;\nimport io.github.glaforge.gemini.interactions.model.Content.*;\nimport static io.github.glaforge.gemini.interactions.model.Interaction.Role.*;\n\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\n        new Turn(USER, \"Hello!\"),\n        new Turn(MODEL, \"Hi! How can I help?\"),\n        new Turn(USER, \"Tell me a joke\")\n    )\n    .build();\n\nInteraction response = client.create(request);\n```\n\n### Multi-turn Conversation with Persistence\n\nYou can also continue a conversation by referencing the ID of a previous interaction. Ensure you set `store(true)` to persist the interaction context.\n\n```java\n// 1. First turn (must set store=true)\nModelInteractionParams turn1 = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\"Hello!\")\n    .store(true)\n    .build();\n\nInteraction response1 = client.create(turn1);\nString id = response1.id();\nSystem.out.println(response1.outputs().get(0));\n\n// 2. Second turn (referencing previous ID)\nModelInteractionParams turn2 = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\"Tell me a joke\")\n    .previousInteractionId(id)\n    .store(true) // Optional if you want to extend further\n    .build();\n\nInteraction response2 = client.create(turn2);\nSystem.out.println(response2.outputs().get(0));\n```\n\n### Multimodal (Image)\n```java\nimport io.github.glaforge.gemini.interactions.model.Content.*;\n\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\n        new TextContent(\"Describe this image\"),\n        // Create an image from Base64 bytes\n        new ImageContent(imageBytes, \"image/png\")\n    )\n    .build();\n\nInteraction response = client.create(request);\n```\n\n### Multimodal (Audio)\n```java\nimport io.github.glaforge.gemini.interactions.model.Content.*;\nimport io.github.glaforge.gemini.interactions.model.Config.SpeechConfig;\n\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\n        new TextContent(\"Transcribe this audio\"),\n        new AudioContent(audioBytes, \"audio/mp3\")\n    )\n    .build();\n\nInteraction response = client.create(request);\n```\n\n### Image Generation (Nano Banana Pro)\n```java\nimport io.github.glaforge.gemini.interactions.model.Content.*;\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;\nimport io.github.glaforge.gemini.interactions.model.Interaction.Modality;\n\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"gemini-3-pro-image-preview\")\n    .input(\"Create an infographic about blood, organs, and the circulatory system\")\n    .responseModalities(Modality.IMAGE)\n    .build();\n\nInteraction interaction = client.create(request);\n\ninteraction.outputs().forEach(content -\u003e {\n    if (content instanceof ImageContent image) {\n        byte[] imageBytes = Base64.getDecoder().decode(image.data());\n        // Save imageBytes to a file\n    }\n});\n```\n\n### Audio Output\n```java\nimport io.github.glaforge.gemini.interactions.model.Content.*;\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;\nimport io.github.glaforge.gemini.interactions.model.Interaction.Modality;\nimport io.github.glaforge.gemini.interactions.model.Config.SpeechConfig;\n\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash-preview-tts\")\n    .input(\"Hey, we can generate audio too!\")\n    .responseModalities(Modality.AUDIO, Modality.TEXT)\n    .speechConfig(new SpeechConfig(\"Puck\", \"en-US\"))\n    .build();\n\nInteraction interaction = client.create(request);\n\ninteraction.outputs().forEach(content -\u003e {\n    if (content instanceof AudioContent audio) {\n        byte[] audioBytes = audio.data();\n        // Save audioBytes to a raw PCM file (16-bit little-endian, 24kHz, mono)\n    }\n});\n```\n\n### Lyria Music Generation\n```java\nimport io.github.glaforge.gemini.interactions.model.Content.*;\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;\nimport io.github.glaforge.gemini.interactions.model.Interaction.Modality;\nimport java.nio.file.Files;\nimport java.nio.file.Paths;\n\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"models/lyria-3-clip-preview\")\n    .input(\"An epic song with opera voices about a quest. Deep synths and a speeding up tempo.\")\n    .responseModalities(Modality.AUDIO, Modality.TEXT)\n    .build();\n\nInteraction interaction = client.create(request);\n\ninteraction.outputs().forEach(content -\u003e {\n    if (content instanceof TextContent text) {\n        System.out.println(\"Lyrics / Structure Generated:\\\\n\" + text.text());\n    }\n    if (content instanceof AudioContent audio) {\n        // Lyria directly returns an encoded MP3 byte stream!\n        try {\n            Files.write(Paths.get(\"quest-song.mp3\"), audio.data());\n        } catch (Exception e) {\n            e.printStackTrace();\n        }\n    }\n});\n```\n\n### Deep Research\n```java\nimport io.github.glaforge.gemini.interactions.model.Interaction;\nimport io.github.glaforge.gemini.interactions.model.Interaction.Status;\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.AgentInteractionParams;\n\nAgentInteractionParams request = AgentInteractionParams.builder()\n    .agent(\"deep-research-pro-preview-12-2025\")\n    .input(\"Research the history of the Google TPUs\")\n    .build();\n\nInteraction interaction = client.create(request);\n\n// Poll for completion\nwhile (interaction.status() != Status.COMPLETED) {\n    Thread.sleep(1000);\n    interaction = client.get(interaction.id());\n}\n\nSystem.out.println(interaction.outputs());\n```\n\n### Function Calling\n```java\nimport io.github.glaforge.gemini.interactions.model.Content;\nimport io.github.glaforge.gemini.interactions.model.Content.*;\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;\nimport io.github.glaforge.gemini.interactions.model.Tool;\nimport io.github.glaforge.gemini.interactions.model.Tool.Function;\n\n// 1. Define the tool\nFunction weatherTool = Function.builder()\n    .name(\"get_weather\")\n    .description(\"Get the current weather\")\n    .parameters(\n        Map.of(\n            \"type\", \"object\",\n            \"properties\", Map.of(\n            \"location\", Map.of(\"type\", \"string\")\n        ),\n        \"required\", List.of(\"location\")\n    )\n    .build();\n\n// 2. Initial Request with Tools\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\"What is the weather in London?\")\n    .tools(weatherTool)\n    .build();\n\nInteraction interaction = client.create(request);\n\n// 3. Handle Function Call\nContent lastOutput = interaction.outputs().getLast();\nif (lastOutput instanceof FunctionCallContent call) {\n    if (\"get_weather\".equals(call.name())) {\n        String location = (String) call.arguments().get(\"location\");\n        // Execute local logic...\n        String weather = \"Rainy, 15°C\"; // Simulated result\n\n        // 4. Send Function Result\n        ModelInteractionParams continuation = ModelInteractionParams.builder()\n            .model(\"gemini-2.5-flash\")\n            .previousInteractionId(interaction.id())\n            .input(new FunctionResultContent(\n                \"function_result\",\n                call.id(),\n                call.name(),\n                false,\n                Map.of(\"weather\", weather)\n            ))\n            .build();\n\n        Interaction finalResponse = client.create(continuation);\n        System.out.println(finalResponse.outputs().getLast());\n    }\n}\n```\n\n### Gemma Open Models\n\nYou can use the open Gemma models through the interactions API just like the standard Gemini models.\n\n#### Simple Interaction (Gemma 4 26B)\n```java\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;\nimport io.github.glaforge.gemini.interactions.model.Interaction;\n\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"models/gemma-4-26b-a4b-it\")\n    .input(\"What is the capital of France? Answer in one word.\")\n    .build();\n\nInteraction interaction = client.create(request);\nSystem.out.println(interaction.outputs().getLast());\n```\n\n#### Grounded Search (Gemma 4 31B)\nGemma 4 models fully support the Google Search grounding tool.\n\n```java\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;\nimport io.github.glaforge.gemini.interactions.model.Interaction;\nimport io.github.glaforge.gemini.interactions.model.Tool;\n\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"models/gemma-4-31b-it\")\n    .input(\"Who is the actress who invented the MemPalace agent memory project?\")\n    .tools(new Tool.GoogleSearch())\n    .build();\n\nInteraction interaction = client.create(request);\nSystem.out.println(interaction.outputs().getLast());\n```\n\n### Built-in Tools (Google Maps)\n```java\nimport io.github.glaforge.gemini.interactions.model.Content;\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;\nimport io.github.glaforge.gemini.interactions.model.Tool;\n\n// 1. Define the Google Maps tool\nTool googleMaps = new Tool.GoogleMaps();\n\n// 2. Initial Request with the Tool\nModelInteractionParams request = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\"Can you recommend some good restaurants near the Eiffel tower in Paris?\")\n    .tools(googleMaps)\n    .build();\n\nInteraction interaction = client.create(request);\n\n// 3. Handle Result\nSystem.out.println(interaction.outputs().getLast());\n```\n\n### JSON Output (Structured Output)\nYou can enforce the model to output a specific JSON structure using the `responseFormat` parameter.\n\n#### Map-based Approach\nYou can pass a `Map` representing the JSON Schema directly.\n\n```java\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;\nimport java.util.Map;\nimport java.util.List;\n\nModelInteractionParams params = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\"List 5 popular cookie recipes\")\n    .responseMimeType(\"application/json\")\n    .responseFormat(Map.of(\n        \"type\", \"array\",\n        \"items\", Map.of(\n            \"type\", \"object\",\n            \"properties\", Map.of(\n                \"recipe_name\", Map.of(\"type\", \"string\")\n            )\n        )\n    ))\n    .build();\n```\n\n#### Schema Builder Approach\nYou can use the fluent Schema builder API provided by the SDK.\n\n```java\nimport io.github.glaforge.gemini.interactions.model.InteractionParams.ModelInteractionParams;\nimport io.github.glaforge.gemini.schema.GSchema;\nimport static io.github.glaforge.gemini.schema.GSchema.*;\n\nModelInteractionParams params = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\"List 5 popular cookie recipes\")\n    .responseMimeType(\"application/json\")\n    .responseFormat(\n        arr().items(\n            obj()\n                .prop(\"recipe_name\", str())\n                .prop(\"ingredients\", arr().items(str()))\n        )\n    )\n    .build();\n```\n\n#### From Java Class\nYou can generate the schema directly from a Java class (Records or POJOs).\n\n```java\npublic record Recipe(String name, List\u003cString\u003e ingredients) {}\n\nModelInteractionParams params = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\"List 5 popular cookie recipes\")\n    .responseMimeType(\"application/json\")\n    .responseFormat(GSchema.fromClass(Recipe.class))\n    .build();\n```\n\n#### From JSON Schema String\nYou can also parse an existing JSON Schema string.\n\n```java\nString jsonSchema = \"\"\"\n    {\n      \"type\": \"array\",\n      \"items\": { \"type\": \"string\" }\n    }\n    \"\"\";\n\nModelInteractionParams params = ModelInteractionParams.builder()\n    .model(\"gemini-2.5-flash\")\n    .input(\"List 5 popular cookie recipes\")\n    .responseMimeType(\"application/json\")\n    .responseFormat(GSchema.fromJson(jsonSchema))\n    .build();\n```\n\n## License\nApache 2.0\n\n## Disclaimer\nThis is not an official Google project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglaforge%2Fgemini-interactions-api-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglaforge%2Fgemini-interactions-api-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglaforge%2Fgemini-interactions-api-sdk/lists"}