Name: Google Gemma 3 27B IT Multimodal Chat LLM API
Brand: magicapi
SKU: api-magicapi-ai-models-high-performance-google-gemma-google-deepmind-gemma-3-27b-it
Availability: InStock
Author: API Market

Shashank Agarwal

# 🧠 Multimodal Chat LLM API (Google Gemma 3 27B IT)

## Overview
Gemma 3 27B IT is the 27B parameter, instruction-tuned member of Gemma 3, a family of open models from Google. Its developer describes Gemma as lightweight, state-of-the-art open models built from the same research and technology used to create the Gemini models.

Send a text `prompt` and, optionally, one `image` URL. Steer the model with `system_prompt` and control length and sampling with `max_new_tokens`, `temperature`, `top_p` and `top_k`. The reply comes back as a single string in `output`.

## Features
- **Text and image input**: ask about one `image` per request, or send text only.
- **System prompt**: `system_prompt` sets the assistant's role (default `You are a helpful assistant.`).
- **Output length**: `max_new_tokens` from 1 to 8192 (default `512`).
- **Sampling controls**: `temperature` 0 to 2 (default `0.7`), `top_p` 0 to 1 (default `0.9`), `top_k` 0 to 100 (default `50`).
- **Open model**: Gemma 3 is an open model family from Google.

## Use Cases
1. **Image description**: describe photos for alt text, catalogs or search indexes.
2. **Visual questions**: ask about what is in an image, such as objects, colors or text.
3. **Text tasks**: summarize, rewrite, classify or extract information from text in the prompt.
4. **Chat assistants**: answer user questions with a fixed `system_prompt` for tone and role.

## Visual Examples
### Example Input
Text only (no `image`):

- `prompt`: "Explain in three short sentences why the sky looks blue at noon and red at sunset."
- `system_prompt`: "You are a helpful assistant."
- `max_new_tokens` `512`, `temperature` `0.7`, `top_p` `0.9`, `top_k` `50`

### Example Output
The full reply:

```text
The sky appears blue at noon because of a phenomenon called Rayleigh scattering, where shorter blue wavelengths of sunlight are scattered more by air molecules in all directions. At sunset, the sunlight travels through more of the atmosphere, scattering away most of the blue light. This leaves the longer wavelengths like red and orange to reach our eyes, creating those vibrant sunset colors.



<end_of_turn>
```

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | none |  | Text prompt for the model |
| `image` | string (URL) | No | none |  | Optional image URL for multimodal tasks (for example describing or asking about an image) |
| `system_prompt` | string | No | `You are a helpful assistant.` |  | System prompt to guide the model's behavior |
| `max_new_tokens` | integer | No | `512` | `1` to `8192` | Maximum number of tokens to generate |
| `temperature` | number | No | `0.7` | `0` to `2` | Sampling temperature |
| `top_p` | number | No | `0.9` | `0` to `1` | Top-p (nucleus) sampling |
| `top_k` | integer | No | `50` | `0` to `100` | Top-k sampling |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.019 per API unit.
- **1 API unit = 1 request with up to 11 seconds of processing.** A request that needs more processing time is billed one more unit for each started 11-second block. Processing time grows with the length of the answer (`max_new_tokens`) and with image input.
- **Example cost**: the example request processed for 6.11 seconds, so it used 1 API unit and cost $0.019.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/ai-models-high-performance-google-gemma-google-deepmind-gemma-3-27b-it`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-models-high-performance-google-gemma-google-deepmind-gemma-3-27b-it/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "c0f0aebe8e578c15a7531e08a62cf01206f5870e9d0a67804b8152822db58c54",
    "input": {
      "prompt": "Explain in three short sentences why the sky looks blue at noon and red at sunset.",
      "system_prompt": "You are a helpful assistant.",
      "max_new_tokens": 512,
      "temperature": 0.7,
      "top_p": 0.9,
      "top_k": 50
    }
  }'
```

Response (201 Created):
```json
{
  "id": "3te6et7sdhrn80d1mvj8sdrpam",
  "version": "c0f0aebe8e578c15a7531e08a62cf01206f5870e9d0a67804b8152822db58c54",
  "status": "starting",
  "created_at": "2026-11-04T14:09:46.348Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-models-high-performance-google-gemma-google-deepmind-gemma-3-27b-it/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "3te6et7sdhrn80d1mvj8sdrpam",
  "status": "succeeded",
  "output": "The sky appears blue at noon because of a phenomenon called Rayleigh scattering, where shorter blue wavelengths of sunlight are scattered more by air molecules in all directions. At sunset, the sunlight travels through more of the atmosphere, scattering away most of the blue light. This leaves the longer wavelengths like red and orange to reach our eyes, creating those vibrant sunset colors.\n\n\n\n<end_of_turn>",
  "error": null,
  "created_at": "2026-11-04T14:09:46.348Z",
  "started_at": "2026-11-04T14:11:54.184471805Z",
  "completed_at": "2026-11-04T14:12:00.291936464Z"
}
```

`output` is a single string with the model's whole reply. The reply can end with blank lines and the literal marker `<end_of_turn>`; remove them before showing the text.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `prompt`, a `max_new_tokens` above 8192 or a `temperature` above 2.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
Requests are rate limited to keep usage fair. If you receive a 429 response, wait and retry with exponential backoff.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-models-high-performance-google-gemma-google-deepmind-gemma-3-27b-it";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "c0f0aebe8e578c15a7531e08a62cf01206f5870e9d0a67804b8152822db58c54", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "prompt": "Explain in three short sentences why the sky looks blue at noon and red at sunset.",
  "system_prompt": "You are a helpful assistant.",
  "max_new_tokens": 512,
  "temperature": 0.7,
  "top_p": 0.9,
  "top_k": 50
}).then((output) => console.log(output.replace("<end_of_turn>", "").trim()));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-models-high-performance-google-gemma-google-deepmind-gemma-3-27b-it"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "c0f0aebe8e578c15a7531e08a62cf01206f5870e9d0a67804b8152822db58c54", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


print(create_and_wait_for_prediction({
    "prompt": "Explain in three short sentences why the sky looks blue at noon and red at sunset.",
    "system_prompt": "You are a helpful assistant.",
    "max_new_tokens": 512,
    "temperature": 0.7,
    "top_p": 0.9,
    "top_k": 50
}).replace("<end_of_turn>", "").strip())
```

## FAQ
- **Can I send an image?**
  - Yes. Put one image URL in `image` and ask about it in `prompt`. Leave `image` out for text-only requests.
- **How long can the answer be?**
  - Up to `max_new_tokens` tokens, from 1 to 8192 (default 512). Longer answers take longer to generate and can use more API units.
- **Why does the answer end with `<end_of_turn>`?**
  - That is the model's end-of-reply marker. It is part of the returned string; strip it before display, as the code examples do.
- **How do I get more predictable answers?**
  - Lower `temperature` (for example 0.2) and keep `system_prompt` specific. Higher values give more varied text.
- **How is a request billed?**
  - By processing time: $0.019 per started block of 11 seconds. The example processed for 6.11 seconds and cost $0.019.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us
If you have any questions, reach out to us through the chat on the bottom right of the page.


Run Google's open Gemma 3 27B IT model: answer prompts, describe images and follow a system prompt. $0.019 per request with up to 11 seconds of processing, pay as you go.