Gemini API
Spice serves the Gemini API on /v1beta/models. Gemini clients, such as the Antigravity CLI that spice agy starts, work against Spice by setting their base URL to the Spice HTTP endpoint. The model in the URL names any chat model in the Spicepod, from any provider.
The endpoints need no configuration: they are available whenever the runtime serves models, alongside /v1/chat/completions and the Messages API.
| Method and path | Gemini API method |
|---|---|
GET /v1beta/models | models.list |
GET /v1beta/models/{model} | models.get |
POST /v1beta/models/{model}:generateContent | models.generateContent |
POST /v1beta/models/{model}:streamGenerateContent | models.streamGenerateContent |
POST /v1beta/models/{model}:countTokens | models.countTokens, always refused (see Limits) |
Quickstart​
Define one or more chat models in spicepod.yaml:
models:
- from: openai:gpt-4o-mini
name: gpt
params:
openai_api_key: ${ secrets:SPICE_OPENAI_API_KEY }
Start the runtime with spice run, then send a generateContent request that names the Spicepod model:
curl -X POST http://localhost:8090/v1beta/models/gpt:generateContent \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role": "user", "parts": [{"text": "Hello!"}]}]
}'
The response is a Gemini API GenerateContentResponse, with modelVersion set to the Spicepod model name:
{
"candidates": [
{
"content": { "role": "model", "parts": [{ "text": "Hello! How can I help?" }] },
"finishReason": "STOP",
"index": 0
}
],
"usageMetadata": { "promptTokenCount": 3, "candidatesTokenCount": 6, "totalTokenCount": 9 },
"modelVersion": "gpt"
}
POST /v1beta/models/gpt:streamGenerateContent?alt=sse streams the response as server-sent events, one GenerateContentResponse per event. Without alt=sse, :streamGenerateContent returns the responses as one JSON array once the model finishes.
GET /v1beta/models lists the Spicepod's chat models, sorted by name, each as models/<name> with generateContent as its supported method. A model's inputTokenLimit is set when the runtime knows its context window, less its output limit when it has one, and outputTokenLimit when the runtime knows its output limit.
Authentication​
Without runtime.auth, Spice does not check an API key, so a client that requires one can send any value. With runtime.auth configured, send a Spice API key in x-goog-api-key, the header Google's SDKs send, or in X-API-Key or Authorization: Bearer. Spice authenticates the client with this key and never forwards it to the model provider, which receives the credentials in the model's params.
How Models Serve the Gemini API​
Every chat model serves the Gemini API by translation: Spice converts the request into a chat completion for the model and converts the answer back into a Gemini API response. The system instruction, the turns with their text, images, function calls and function responses, the declared functions and toolConfig, and the sampling and output settings of generationConfig are carried over.
Some fields are accepted and have no effect, because a chat completion has no equivalent and the model's own behavior stands in:
safetySettings: the chat model applies its own safety.generationConfig.topK: a chat completion has no top-k sampling.generationConfig.thinkingConfig: a chat completion has no per-request reasoning budget. Set a reasoning model's default effort with the model provider prefix followed byreasoning_effort, such ashf_reasoning_effort, as Parameter Overrides describes. The response carries nothoughtparts.- Tools that Google runs, such as
googleSearch,codeExecution, andurlContext: only the declared functions are offered to the model. - Earlier turns' reasoning (parts marked
thought) andthoughtSignaturevalues.
A field that would change the answer is refused with a 400 INVALID_ARGUMENT error that names it, rather than dropped: more than one candidate, cached content, media other than images, data referenced by URI, code execution history, and output other than text or JSON. A request with no contents is refused the same way.
A decision model does not serve chat completions or the Gemini API, and a request that names one is refused with a 400 that points to POST /v1/decisions.
Limits​
:countTokensis always refused with a400INVALID_ARGUMENTerror, because a token count is specific to the model's tokenizer, which a chat completion does not expose. TheusageMetadataof agenerateContentresponse counts the prompt.- A model in the URL that is not in the Spicepod returns
404with aNOT_FOUNDerror, and a model that failed to load returns503withUNAVAILABLE.
Errors​
Every error from the /v1beta/models routes uses the Gemini API's error body, including authentication failures and errors from the layers in front of the handlers, such as a request body that is too large, so Gemini clients read every error the same way:
{
"error": {
"code": 400,
"message": "The request body is not a valid request: missing field `contents`",
"status": "INVALID_ARGUMENT"
}
}
The response keeps the HTTP status of the failure, such as 401 for a missing API key or 413 for an oversized body. A streamed response that fails after it started sends the same error body as its last event.
