Repository navigation
Expand file tree
/
Copy pathindex.html
More file actions
361 lines (334 loc) · 18.7 KB
/
Copy pathindex.html
File metadata and controls
361 lines (334 loc) · 18.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Gemini — aimock</title>
<link rel="icon" type="image/svg+xml" href="../favicon.svg" />
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:ital,wght@0,300;0,400;0,500;0,600;0,700;1,400&family=Instrument+Sans:wght@400;500;600;700&display=swap"
rel="stylesheet"
/>
<link rel="stylesheet" href="../style.css" />
<script src="/pixels.js" defer></script>
</head>
<body>
<nav class="top-nav">
<div class="nav-inner">
<div style="display: flex; align-items: center; gap: 1rem">
<button
class="sidebar-toggle"
onclick="document.querySelector('.sidebar').classList.toggle('open')"
aria-label="Toggle sidebar"
>
☰
</button>
<a href="/" class="nav-brand"> <span class="prompt">$</span> aimock </a>
</div>
<ul class="nav-links">
<li><a href="/">Home</a></li>
<li><a href="/docs" style="color: var(--accent)">Docs</a></li>
<li>
<a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
<path
d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"
/>
</svg>
GitHub</a
>
</li>
</ul>
</div>
</nav>
<div class="docs-layout">
<aside class="sidebar" id="sidebar"></aside>
<main class="docs-content">
<h1>Google Gemini</h1>
<p class="lead">
aimock supports both <code>generateContent</code> (non-streaming) and
<code>streamGenerateContent</code> (SSE) endpoints, plus Gemini Live over WebSocket. The
same fixtures drive all three transports.
</p>
<p>
To send events or fields aimock does not model yet, use a
<a href="/raw-passthrough">raw passthrough fixture</a> with <code>wire: "gemini"</code>.
</p>
<p>
Fixture <code>citations</code> serve <code>groundingMetadata</code>, and fixture
<code>files</code> serve <code>inlineData</code> parts, such as generated images. See
<a href="/fixtures#citations-and-files">Citations and generated files</a>.
</p>
<h2>Endpoints</h2>
<table class="endpoint-table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Format</th>
</tr>
</thead>
<tbody>
<tr>
<td>POST</td>
<td>/v1beta/models/:model:generateContent</td>
<td>JSON</td>
</tr>
<tr>
<td>POST</td>
<td>/v1beta/models/:model:streamGenerateContent</td>
<td>SSE (data:)</td>
</tr>
<tr>
<td>GET</td>
<td>/v1beta/models</td>
<td>Paged model JSON</td>
</tr>
<tr>
<td>GET</td>
<td>/v1beta/models/:model</td>
<td>Model JSON</td>
</tr>
<tr>
<td>POST</td>
<td>/v1beta/models/:model:countTokens</td>
<td>JSON: totalTokens</td>
</tr>
<tr>
<td>WS</td>
<td>/ws/google.ai.generativelanguage.*</td>
<td>WebSocket JSON</td>
</tr>
</tbody>
</table>
<p>
If the client hangs up before the reply is complete, aimock stops delivery and journals
the request with <code>interruptReason: "client aborted"</code> (see
<a href="/error-injection#client-disconnects">Client Disconnects</a>). Gemini Live records
the turn the same way. To delay <code>generateContent</code> replies, set
<code>nonStreamingTimingAllProviders: true</code> with a <code>streamingProfile</code> or
<code>recordedTimings</code> (see
<a href="/streaming-physics#non-streaming-all-providers">All Providers</a>).
</p>
<h2 id="model-catalog">Model Catalog</h2>
<p>
The native catalog contains Google IDs and unrecognized IDs from fixtures, in first-seen
order. Empty fixture sets use the established default models. Known OpenAI and Anthropic
IDs are excluded. Custom test IDs remain visible.
</p>
<p>
<code>GET /v1beta/models</code> returns <code>models</code> and a
<code>nextPageToken</code> when another page exists. The default <code>pageSize</code> is
50. Zero uses that default, and values greater than 1000 use 1000. Send the returned token
as <code>pageToken</code> for the next page.
</p>
<p>
A client that ignores <code>nextPageToken</code> sees only the first page. Negative,
noninteger, or nonnumeric sizes and invalid tokens return 400
<code>INVALID_ARGUMENT</code>. aimock uses base64 offset tokens. Exact error details are
local contracts. Authenticated upstream catalog errors were not measured.
</p>
<p>
Model metadata is synthetic: <code>name</code> is <code>models/<id></code>,
<code>baseModelId</code> and <code>displayName</code> equal the ID, and
<code>version</code> is <code>"1"</code>. Token limits are 128000 input and 8192 output.
<code>supportedGenerationMethods</code> contains <code>generateContent</code> and
<code>countTokens</code>. These values do not describe upstream capacity.
</p>
<p>
Detail paths accept raw or percent-encoded slashes in IDs. Missing IDs, malformed escapes,
and IDs outside the Google catalog return 404 <code>NOT_FOUND</code>. The examples assume
fixtures with <code>gemini-test</code> and additional Gemini IDs.
</p>
<div class="code-block">
<div class="code-block-header">Native catalog <span class="lang-tag">shell</span></div>
<pre><code>curl 'http://localhost:4010/v1beta/models?pageSize=1'
curl 'http://localhost:4010/v1beta/models?pageSize=1&pageToken=MQ=='
curl 'http://localhost:4010/v1beta/models/gemini-test'</code></pre>
</div>
<p>
In this example, the first page returns <code>MQ==</code>. Use the actual returned token
for your fixture set.
</p>
<h2 id="token-counts">Approximate Token Counts</h2>
<p>
<code>POST /v1beta/models/:model:countTokens</code> accepts top-level
<code>contents</code> or a <code>generateContentRequest</code> wrapper. It returns
<code>{"totalTokens": N}</code>. Wrapped requests use the fields inside the wrapper,
including system text and tools.
</p>
<p>
aimock converts the request through its existing translator, then estimates about 1 token
per 4 characters of messages (plus tool definitions), minimum 1. The estimate includes
converted messages, system text, and serialized converted tools. This deterministic
estimate is not a tokenizer or an upstream count. Optional cache counts and token-detail
arrays are omitted.
</p>
<div class="code-block">
<div class="code-block-header">Count a prompt <span class="lang-tag">shell</span></div>
<pre><code>curl http://localhost:4010/v1beta/models/gemini-test:countTokens \
-H 'Content-Type: application/json' \
--data '{"contents":[{"role":"user","parts":[{"text":"hello"}]}]}'
curl http://localhost:4010/v1beta/models/gemini-test:countTokens \
-H 'Content-Type: application/json' \
--data '{"generateContentRequest":{"contents":[{"role":"user","parts":[{"text":"hello"}]}]}}'</code></pre>
</div>
<p>
Counts ignore fixture usage. Generate responses use fixture counts and otherwise default
to zero. To make a response agree with an estimate, set its fixture usage explicitly.
Missing or invalid contents return 400 <code>INVALID_ARGUMENT</code>.
</p>
<p>
Catalog and count routes never proxy or record. Count POSTs create internal journal
entries. Catalog GETs do not. See
<a href="/record-replay#catalog-and-count-routes">Record & Replay</a>.
</p>
<h2 id="authentication-errors">Authentication Errors</h2>
<p>
With inbound API-key authentication enabled, rejected keys on Gemini and Vertex Google
HTTP paths return 401 with the same body as every other HTTP route, unchanged from 1.45:
</p>
<div class="code-block">
<div class="code-block-header">
Default inbound rejection <span class="lang-tag">json</span>
</div>
<pre><code>{"error":{"message":"Invalid API key","type":"authentication_error","code":"invalid_api_key"}}</code></pre>
</div>
<p>
To get the provider-native body instead, set <code>policy.authErrors</code> to
<code>"native"</code>, pass <code>--policy authErrors=native</code>, or send the request
header <code>X-AIMock-Policy: authErrors=native</code>. Gemini and Vertex Google HTTP
paths then return:
</p>
<div class="code-block">
<div class="code-block-header">
Native inbound rejection <span class="lang-tag">json</span>
</div>
<pre><code>{"error":{"code":401,"message":"Invalid API key","status":"UNAUTHENTICATED"}}</code></pre>
</div>
<p>
The native body uses the numeric <code>error.code: 401</code> and
<code>error.status: "UNAUTHENTICATED"</code> in place of the string
<code>error.code: "invalid_api_key"</code>. With the native policy, check HTTP 401 or the
status string.
</p>
<p>
A live unauthenticated Gemini count probe returned 403 <code>PERMISSION_DENIED</code>
for an unregistered caller. The native aimock body intentionally keeps 401
<code>UNAUTHENTICATED</code> for configured inbound authentication. These policies differ.
WebSocket authentication always returns the default body.
</p>
<h2>Unit Test: Streaming Text</h2>
<div class="code-block">
<div class="code-block-header">gemini-text.test.ts <span class="lang-tag">ts</span></div>
<pre><code><span class="kw">const</span> <span class="op">textFixture</span> = {
<span class="prop">match</span>: { <span class="prop">userMessage</span>: <span class="str">"hello"</span> },
<span class="prop">response</span>: { <span class="prop">content</span>: <span class="str">"Hi there!"</span> },
};
<span class="kw">const</span> <span class="op">instance</span> = <span class="kw">await</span> <span class="fn">createServer</span>([<span class="op">textFixture</span>]);
<span class="kw">const</span> <span class="op">res</span> = <span class="kw">await</span> <span class="fn">post</span>(
<span class="str">`${instance.url}/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse`</span>,
{
<span class="prop">contents</span>: [{ <span class="prop">role</span>: <span class="str">"user"</span>, <span class="prop">parts</span>: [{ <span class="prop">text</span>: <span class="str">"hello"</span> }] }],
}
);
<span class="cm">// Parse Gemini SSE chunks</span>
<span class="kw">const</span> <span class="op">chunks</span> = <span class="op">res</span>.<span class="prop">body</span>.<span class="fn">split</span>(<span class="str">"\n"</span>)
.<span class="fn">filter</span>(<span class="op">l</span> <span class="kw">=></span> <span class="op">l</span>.<span class="fn">startsWith</span>(<span class="str">"data: "</span>))
.<span class="fn">map</span>(<span class="op">l</span> <span class="kw">=></span> <span class="type">JSON</span>.<span class="fn">parse</span>(<span class="op">l</span>.<span class="fn">slice</span>(<span class="num">6</span>)));
<span class="cm">// Gemini response shape</span>
<span class="fn">expect</span>(<span class="op">chunks</span>[<span class="num">0</span>].<span class="prop">candidates</span>[<span class="num">0</span>].<span class="prop">content</span>.<span class="prop">parts</span>[<span class="num">0</span>].<span class="prop">text</span>).<span class="fn">toBeDefined</span>();
<span class="cm">// Reassemble text</span>
<span class="kw">const</span> <span class="op">text</span> = <span class="op">chunks</span>
.<span class="fn">map</span>(<span class="op">c</span> <span class="kw">=></span> <span class="op">c</span>.<span class="prop">candidates</span>[<span class="num">0</span>].<span class="prop">content</span>.<span class="prop">parts</span>[<span class="num">0</span>].<span class="prop">text</span> ?? <span class="str">""</span>)
.<span class="fn">join</span>(<span class="str">""</span>);
<span class="fn">expect</span>(<span class="op">text</span>).<span class="fn">toBe</span>(<span class="str">"Hi there!"</span>);</code></pre>
</div>
<h2>Unit Test: Tool Call</h2>
<div class="code-block">
<div class="code-block-header">gemini-tools.test.ts <span class="lang-tag">ts</span></div>
<pre><code><span class="kw">const</span> <span class="op">toolFixture</span> = {
<span class="prop">match</span>: { <span class="prop">userMessage</span>: <span class="str">"weather"</span> },
<span class="prop">response</span>: {
<span class="prop">toolCalls</span>: [{ <span class="prop">name</span>: <span class="str">"get_weather"</span>, <span class="prop">arguments</span>: { <span class="prop">city</span>: <span class="str">"NYC"</span> } }]
},
};
<span class="kw">const</span> <span class="op">instance</span> = <span class="kw">await</span> <span class="fn">createServer</span>([<span class="op">toolFixture</span>]);
<span class="kw">const</span> <span class="op">res</span> = <span class="kw">await</span> <span class="fn">post</span>(
<span class="str">`${instance.url}/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse`</span>,
{
<span class="prop">contents</span>: [{ <span class="prop">role</span>: <span class="str">"user"</span>, <span class="prop">parts</span>: [{ <span class="prop">text</span>: <span class="str">"what is the weather?"</span> }] }],
}
);
<span class="kw">const</span> <span class="op">chunks</span> = <span class="fn">parseGeminiSSEChunks</span>(<span class="op">res</span>.<span class="prop">body</span>);
<span class="kw">const</span> <span class="op">parts</span> = <span class="op">chunks</span>[<span class="num">0</span>].<span class="prop">candidates</span>[<span class="num">0</span>].<span class="prop">content</span>.<span class="prop">parts</span>;
<span class="fn">expect</span>(<span class="op">parts</span>[<span class="num">0</span>].<span class="prop">functionCall</span>.<span class="prop">name</span>).<span class="fn">toBe</span>(<span class="str">"get_weather"</span>);</code></pre>
</div>
<h2>Request Translation</h2>
<p>
Gemini uses a different request format (<code>contents</code> with <code>parts</code>)
than OpenAI. aimock translates Gemini requests to the unified format via
<code>geminiToCompletionRequest()</code> so the same fixture
<code>match.userMessage</code> works regardless of which provider endpoint the request
arrives on.
</p>
<h2>Gemini Live (WebSocket)</h2>
<p>
Gemini Live uses WebSocket at <code>/ws/google.ai.generativelanguage.*</code> for
bidirectional streaming. See the <a href="/websocket">WebSocket APIs</a> page for details.
</p>
<div class="info-box">
<p>
Gemini Live text support is unverified against a real model — no text-capable
Gemini Live model existed at time of writing. The implementation follows the API
specification.
</p>
</div>
<h2>Vertex AI</h2>
<p>
Google Cloud's <strong>Vertex AI</strong> provides access to Gemini models through a
different URL pattern than the AI Studio API. aimock supports Vertex AI requests using the
same Gemini handler — the URL pattern is different, but the request and response
formats are identical.
</p>
<p>Vertex AI URLs follow the pattern:</p>
<div class="code-block">
<div class="code-block-header">
Vertex AI URL pattern <span class="lang-tag">text</span>
</div>
<pre><code>POST /v1/projects/{project}/locations/{location}/publishers/google/models/{model}:generateContent
POST /v1/projects/{project}/locations/{location}/publishers/google/models/{model}:streamGenerateContent</code></pre>
</div>
<p>
The same fixtures work for both Gemini AI Studio and Vertex AI endpoints. See the
<a href="/vertex-ai">Vertex AI</a> page for configuration details.
</p>
<h2>Ordered blocks (tool-first)</h2>
<p>
A combined <code>content</code> + <code>toolCalls</code> fixture accepts an optional
<code>blocks</code> array to control stream order — see
<a href="/fixtures#ordered-blocks">Ordered blocks</a>. Gemini has
<strong>full</strong> support: ordered parts/candidate chunks carry
<code>functionCall</code> and text in array order, so tool-first and interleaved ordering
are observable to clients.
</p>
</main>
<aside class="page-toc" id="page-toc"></aside>
</div>
<footer class="docs-footer">
<div class="footer-inner">
<div class="footer-left"><span>$</span> aimock · MIT License</div>
<ul class="footer-links">
<li><a href="https://github.com/CopilotKit/aimock" target="_blank">GitHub</a></li>
<li>
<a href="https://www.npmjs.com/package/@copilotkit/aimock" target="_blank">npm</a>
</li>
</ul>
</div>
</footer>
<script src="../sidebar.js"></script>
<script src="../cli-tabs.js"></script>
</body>
</html>