Name: Gemini 2.5 Flash API: Fast Multimodal Chat and Reasoning
Brand: magicapi
SKU: api-magicapi-ai-content-generator-google-gemini-2-5-flash
Availability: InStock
Author: API Market

Shashank Agarwal

# 🧠 Multimodal Chat and Reasoning API (Google Gemini 2.5 Flash)

## Overview
Gemini 2.5 Flash is a language model from Google that reads text, images and videos and answers in text. Its developer describes it as a hybrid "thinking" model optimized for speed and cost-efficiency.

Send a `prompt`, optionally with up to 10 `images` and up to 10 `videos`, and the model returns its answer. Control how much it reasons before answering with `thinking_budget` or `dynamic_thinking`, and steer its behavior with `system_instruction`.

## Features
- **Text, image and video input**: up to 10 images (each up to 7MB) and up to 10 videos (each up to 45 minutes) in one request.
- **Adjustable thinking**: `thinking_budget` sets how many tokens the model may spend reasoning (0 to 24576; 0 turns thinking off). Set `dynamic_thinking` to `true` to let the model pick the budget from the complexity of the request; it overrides `thinking_budget`.
- **System instruction**: set a role, tone or output format with `system_instruction`.
- **Long answers**: `max_output_tokens` goes up to 65535, which is also the default.
- **Sampling control**: `temperature` (0 to 2, default 1) and `top_p` (0 to 1, default 0.95).

## Use Cases
1. **Image descriptions**: detailed descriptions and alt text for photos, illustrations and screenshots.
2. **Video questions**: ask what happens in a video, or compare several videos in one request.
3. **Writing and summarizing**: draft, rewrite or summarize text from a prompt and a system instruction.
4. **Reasoning tasks**: math, planning and code questions with a higher thinking budget.

## Visual Examples
### Example Input
Prompt: "describe this image in detail"

Image:

![Painting of a samurai in purple and white armor sitting under an autumn tree in front of snowy mountains](https://blog.api.market/wp-content/uploads/2026/10/gemini-2-5-flash-input-api-market.jpg)

Settings: `temperature` 1, `top_p` 0.95, `max_output_tokens` 2048, `dynamic_thinking` `false`, no videos.

### Example Output
The joined `output` text:

> This is a stunning, painterly image depicting a solitary samurai warrior in contemplation amidst a dramatic autumn mountain landscape. The artistic style blends realism with an expressive, almost fantastical quality, reminiscent of traditional Japanese art mixed with modern digital painting techniques.
>
> **Main Subject - The Samurai:**
> Positioned on the left side of the frame, the samurai is seated on a rocky outcrop, his legs tucked beneath him in a meditative or resting posture. His head is bowed, angled slightly away from the viewer, suggesting introspection, reverence, or perhaps weariness.
> He is clad in elaborate, highly detailed traditional samurai armor. The dominant colors of his armor are rich purple and intricate white.
> *   **Helmet (Kabuto):** The helmet is a deep, glossy purple, featuring prominent gold-colored accents, including a decorative crest (maedate) that resembles upward-curving horns or crescent moons. The lacing (odoshi) also appears purple.
> *   **Body Armor:** The main cuirass, shoulder guards, and leg armor are a striking combination of white and purple. The white sections are adorned with delicate, traditional Japanese floral or scrollwork patterns in purple. The purple sections appear to be lacquered or crafted from a material with a subtle sheen. The armored plates are intricately detailed, showing individual segments and lacing.
> *   **Inner Garment/Skin:** His visible skin, particularly around his neck and face, is rendered in an unusual deep blue or dark indigo color, which stands in stark contrast to the armor and adds a mysterious, almost mythical quality to the figure.
> *   **Weapon:** A katana (Japanese sword) in its scabbard is visible tucked into his belt on his left side, its hilt (tsuka) subtly visible.
>
> **Foreground and Midground - Nature:**
> The samurai is nestled beneath the gnarled trunk and branches of an autumnal tree.
> *   **Tree:** A thick, twisted, dark brown trunk rises behind the samurai. Its branches extend across the upper part of the image and sweep dramatically to the right, heavily laden with vibrant autumn foliage.
> *   **Leaves:** The leaves are a brilliant tapestry of reds, oranges, and yellows, with some hints of green, suggesting a peak fall season. The brushstrokes used for the leaves are visible and textural, giving them a rich, almost impasto quality. Small berries or buds are also visible on some branches.
> *   **Rocks:** The samurai sits on a rugged, grey and brown rock formation. The rocks have a rough, craggy texture, with hints of moss or lichen, suggesting a high, exposed location.
>
> **Background - Landscape:**
> The background unfolds into a majestic mountain range under a light, hazy sky.
> *   **Mountains:** Layered mountains recede into the distance. The closest peaks are a muted blue-grey, shrouded in a soft mist. Further back and to the right, a prominent, imposing mountain rises, its peak covered in brilliant white snow. This snow-capped mountain dominates the distant horizon on the right.
> *   **Sky:** The sky is a pale, hazy blue-white, conveying a sense of clear but diffused light, typical of a serene high-altitude morning or late afternoon.
>
> **Color Palette and Mood:**
> The image is dominated by a rich palette of purples, golds, vibrant reds and oranges, contrasted with the stark white of the armor and the cool blues and greys of the distant mountains and sky. The overall mood is one of profound tranquility, dignity, and a touch of somber reflection, set against the breathtaking beauty of nature in its autumn glory. The juxtaposition of the powerful warrior in his ornate armor with the peaceful, natural setting creates a captivating and evocative scene.

This request used 263 input tokens and 767 output tokens.

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes |  |  | The text prompt to send to the model |
| `images` | array of URLs | No | `[]` |  | Input image URLs to send with the prompt (max 10 images, each up to 7MB) |
| `videos` | array of URLs | No | `[]` |  | Input video URLs to send with the prompt (max 10 videos, each up to 45 minutes) |
| `system_instruction` | string | No | none |  | System instruction to guide the model's behavior |
| `temperature` | number | No | `1` | `0` to `2` | Sampling temperature between 0 and 2 |
| `top_p` | number | No | `0.95` | `0` to `1` | Nucleus sampling parameter: the model considers the tokens within the top_p probability mass |
| `max_output_tokens` | integer | No | `65535` | `1` to `65535` | Maximum number of tokens to generate |
| `thinking_budget` | integer | No | none | `0` to `24576` | Thinking budget for reasoning (0 disables thinking, higher values allow more reasoning) |
| `dynamic_thinking` | boolean | No | `false` |  | Let the model adjust the thinking budget to the complexity of the request (overrides thinking_budget) |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.0032 per API unit.
- **1 API unit = 1,000 weighted tokens; an output token counts 1, an input token counts 0.12.**
- That is **$0.384 per million input tokens** and **$3.20 per million output tokens**. Each request is rounded up to a whole API unit.
- Token counts are the input and output token counts the model reports for each request.
- **Example cost**: the example request used 263 input tokens and 767 output tokens. 263 x 0.12 + 767 = 798.56 weighted tokens, which rounds up to 1 API unit: **$0.0032**.
- **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-content-generator-google-gemini-2-5-flash`

### 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. The example request finished in about 13 seconds.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-content-generator-google-gemini-2-5-flash/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "google/gemini-2.5-flash",
    "input": {
      "top_p": 0.95,
      "images": [
        "https://blog.api.market/wp-content/uploads/2026/10/gemini-2-5-flash-input-api-market.jpg"
      ],
      "prompt": "describe this image in detail",
      "videos": [],
      "temperature": 1,
      "dynamic_thinking": false,
      "max_output_tokens": 2048
    }
  }'
```

Response (201 Created):
```json
{
  "id": "5f3ejx8tx1rmt0d1c6s8q6r02g",
  "version": "google/gemini-2.5-flash",
  "status": "starting",
  "created_at": "2026-10-22T03:40:24.838Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-content-generator-google-gemini-2-5-flash/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "5f3ejx8tx1rmt0d1c6s8q6r02g",
  "status": "succeeded",
  "output": [
    "This is a stunning, painterly image depicting a solitary samurai warrior in contemplation amidst a dramatic autumn mountain landscape. The artistic",
    " style blends realism with an expressive, almost fantastical quality, reminiscent of traditional Japanese art mixed with modern digital painting techniques.\n\n**Main Subject - The Samurai:**\nPositioned on the left side of the frame, the samurai is seated on a rocky outcrop",
    ", his legs tucked beneath him in a meditative or resting posture. His head is bowed, angled slightly away from the viewer, suggesting introspection, reverence, or perhaps weariness.\nHe is clad in elaborate, highly detailed traditional samurai armor. The"
  ],
  "error": null,
  "created_at": "2026-10-22T03:40:24.838Z",
  "started_at": "2026-10-22T03:40:25.338Z",
  "completed_at": "2026-10-22T03:40:37.572Z"
}
```

`output` is a list of text chunks. Join them in order to get the full answer. The example above shows only the first 3 of 16 chunks.

### 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` 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
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## 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-content-generator-google-gemini-2-5-flash";

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: "google/gemini-2.5-flash", 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({
    "top_p": 0.95,
    "images": [
      "https://blog.api.market/wp-content/uploads/2026/10/gemini-2-5-flash-input-api-market.jpg"
    ],
    "prompt": "describe this image in detail",
    "videos": [],
    "temperature": 1,
    "dynamic_thinking": false,
    "max_output_tokens": 2048
  }).then((output) => console.log(output.join("")));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-content-generator-google-gemini-2-5-flash"


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": "google/gemini-2.5-flash", "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("".join(create_and_wait_for_prediction({
    "top_p": 0.95,
    "images": [
        "https://blog.api.market/wp-content/uploads/2026/10/gemini-2-5-flash-input-api-market.jpg"
    ],
    "prompt": "describe this image in detail",
    "videos": [],
    "temperature": 1,
    "dynamic_thinking": False,
    "max_output_tokens": 2048
})))
```

## FAQ
- **How do I get the full answer?**
  - `output` is a list of text chunks. Join them in order with no separator.
- **How do I control thinking?**
  - Set `thinking_budget` to 0 to turn thinking off, or to a value up to 24576 to allow more reasoning. Set `dynamic_thinking` to `true` to let the model choose the budget; it overrides `thinking_budget`.
- **How many images and videos can I send?**
  - Up to 10 images (each up to 7MB) and up to 10 videos (each up to 45 minutes), as URLs in `images` and `videos`.
- **What does a request cost?**
  - It depends on the tokens used: $0.384 per million input tokens and $3.20 per million output tokens, rounded up to a whole API unit ($0.0032) per request. The example request cost $0.0032.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **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. You can also email our support team at hello@magicapi.com.


Ask Google's Gemini 2.5 Flash about text, images and videos, with optional thinking before it answers. Pay as you go, no monthly fee.