# Gemini 2.5 Flash

> Proven fast Gemini tier — low-latency multimodal text generation.

## Overview

- **Model ID**: `gemini-2.5-flash`
- **Workflow**: `chat-completions`
- **Provider**: Google
- **Category**: Image → Text (text)
- **Output**: Generated text.
- **Tags**: fast, vision, thinking
- **Unified endpoint**: `POST https://api.picsart.com/workflows/v1/models/execute` (model id in the body)
- **Compatibility endpoint**: `POST https://api.picsart.com/workflows/chat-completions/execute` (vendor's own parameters)
- **Execution**: sync (`/execute`) returns the result in one call; async is also available
- **Model page**: https://picsart.com/api-platform/models/gemini-2.5-flash

## Pricing

Rates are in USD. Every row below is an exact rate for the settings it names — the columns are the settings that change the price for this model. Every response reports what was actually charged in `response.usage.credits`.

| Tier | Rate |
| --- | --- |
| Cached input | $0.033 / 1M cached input tokens |
| Cache write | $0.0834 / 1M cache write tokens |
| Input | $0.30 / 1M input tokens |
| Generation | $0.33 / generation |
| Output text | $2.50 / 1M output text tokens |

Published rates. Volume pricing, invoicing and annual agreements: https://picsart.com/api-platform/contact-sales

## Authentication

The SDK and the REST API authenticate with a Picsart API key sent as a bearer token. Create a key in the console at https://picsart.com/api-platform/dashboard/api-keys, keep it in a server-side environment variable, and never ship it in browser code or commit it.

```bash
export PICSART_API_KEY="YOUR_KEY"
```

```http
Authorization: Bearer $PICSART_API_KEY
```

The CLI and the MCP server do not use an API key: `gen-ai login` signs in through the browser once per machine and stores a token locally.

## Interfaces

- **SDK** — `@picsart/ai-sdk` (TypeScript, Node 20+, ESM). Type-safe `ai.generate()` / `ai.generateText()` with per-model parameter types; polls long jobs for you.
- **REST** — the API gateway at `https://api.picsart.com`. Sync `/execute`, or async `/submit` + `/{taskId}/result`.
- **CLI** — `@picsart/gen-ai` (`gen-ai`). Generate from a terminal, quote cost before spending, emit JSON for pipelines.
- **MCP** — the same models inside Claude Code, Cursor, Windsurf and other MCP hosts. Setup: https://picsart.com/gen-ai-mcp/

```bash
npm install @picsart/ai-sdk      # SDK
npm install -g @picsart/gen-ai   # CLI (also drives the MCP server)
```

## Unified API (recommended)

One parameter set, used by the SDK and by REST alike: the names below are what `ai.generate('gemini-2.5-flash', …)` takes, and what goes inside the inner `params` of a REST call. Over REST the model id travels in the body, not the path — one workflow, `v1/models`, fronts the whole catalogue.

### Execution modes

- **Sync** — `POST /workflows/v1/models/execute` returns the result in one call. Only for jobs that finish within ~20 seconds; otherwise it times out.
- **Async** — `POST /workflows/v1/models/submit` returns a task id; poll `GET /workflows/v1/models/{taskId}/result` until `response.status` is `COMPLETED` or `FAILED`. Task statuses: `ACCEPTED` · `IN_PROGRESS` · `COMPLETED` · `FAILED`.
- **SDK** — `ai.generate()` always awaits the finished result; polling is hidden.

### Input parameters

- **`prompt`** (`string`, _required_): Prompt
- **`imageUrls`** (`list<string>`, _optional_): Images
  - Accepts: image URLs (max 8)
- **`thinking`** (`string`, _optional_): Thinking
  - Default: `"off"`
  - Options: `off`, `low`, `medium`, `high`

### Input JSON Schema

The inner `params` object. Over REST it is wrapped as `{ "params": { "model": "<id>", "params": <this> } }`; the SDK takes it directly.

```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "description": "Prompt"
    },
    "imageUrls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "description": "image URL"
      },
      "maxItems": 8,
      "description": "Images"
    },
    "thinking": {
      "type": "string",
      "enum": [
        "off",
        "low",
        "medium",
        "high"
      ],
      "default": "off",
      "description": "Thinking"
    }
  },
  "additionalProperties": false
}
```

### Required parameters example

The required parameters plus the defaults that shape the output, as a REST body:

```json
{
  "params": {
    "model": "gemini-2.5-flash",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed"
    }
  }
}
```

### Response

The body is the gateway's status envelope: the output is at `response.result`, next to the task id, its status and the credits charged. Text models return `text`.

```json
{
  "status": "success",
  "response": {
    "id": "task_abc123",
    "status": "COMPLETED",
    "result": {
      "text": "…generated text…",
      "model": "gemini-2.5-flash"
    }
  }
}
```

What `ai.generate()` / `ai.generateText()` resolve to (the envelope already unwrapped):

```json
{
  "text": "…generated text…",
  "model": "gemini-2.5-flash"
}
```

### Usage examples

#### TypeScript (SDK)

```typescript
import { createClient } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

const { text } = await ai.generateText('gemini-2.5-flash', {
  prompt: "A serene mountain lake at golden hour, ultra detailed"
});

console.log(text);
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/v1/models/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "model": "gemini-2.5-flash",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed"
    }
  }
}'
```

#### CLI

```bash
gen-ai login  # once per machine
gen-ai models info gemini-2.5-flash  # this model's parameters
gen-ai pricing gemini-2.5-flash  # quote before spending credits
gen-ai generate -m gemini-2.5-flash \
  -p "A serene mountain lake at golden hour"
```

## Compatibility API (vendor parameters)

Alongside the unified API, the `chat-completions` workflow takes Google's own parameters exactly as the vendor defines them — nothing renamed or reshaped. It is the shortest path onto Picsart for request bodies already written against the vendor; the trade is that a request is written for one vendor, and the result comes back in the vendor's own shape. Same authentication.

- **Endpoint**: `POST https://api.picsart.com/workflows/chat-completions/execute` (sync) · `POST …/submit` + `GET …/{taskId}/result` (async)
- **SDK**: `ai.apis.run('chat-completions', params, { mode })` — params forwarded verbatim

### Vendor parameters

| Parameter | Type | Required | Default | Details |
| --- | --- | --- | --- | --- |
| `model` | `string` | yes | — | Model used for completions · Options: `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, `gpt-5`, `gpt-5.1`, `gpt-5.2`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5-mini`, `gpt-5-nano`, `gpt-5-search-api`, `gpt-4o`, `gpt-4o-mini`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `claude-sonnet-4-5`, `claude-sonnet-4-6`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-haiku-4-5`, `claude-haiku-5-5`, `claude-fable-5`, `claude-fable-5-1`, `gemini-3.1-pro-preview`, `gemini-3-flash-preview`, `gemini-3.8-flash`, `gemini-3.7-flash`, `gemini-3.6-flash`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`, `gemini-3.1-flash-lite`, `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-4-argon`, `kimi-k3`, `grok-4.7` |
| `messages` | `MessageParam[]` | yes | — | A list of messages comprising the conversation so far |
| └ `name` | `string` | no | — | An optional name for the participant. Provides the model information to differentiate between participants of the same role. |
| └ `role` | `string` | yes | — | The role of the messages author · Options: `developer`, `system`, `user`, `assistant`, `tool` |
| └ `content` | `MessageContentParam[]` | yes | — | An array of content parts with a defined type. Supported options differ based on the model being used to generate the response. Can contain text, image, or audio inputs. Optional on assistant messages that carry tool_calls. |
| └   `type` | `string` | yes | — | The type of the content part.  · Options: `text`, `image_url`, `file` |
| └   `image_url` | `object` | no | — | The image content.  |
| └   `text` | `string` | no | — | The text content.  |
| └   `file` | `object` | no | — | The file content.  |
| └ `tool_calls` | `MessageToolCallParam[]` | no | — | The tool calls generated by the model, echoed back from a previous assistant turn. Echo them exactly as returned — including extra_content — or Gemini 3 models reject the request. |
| └   `id` | `string` | yes | — | The ID of the tool call, as returned by the model. |
| └   `type` | `string` | yes | — | The type of the tool call. Currently, only "function" is supported. |
| └   `function` | `object` | yes | — | The function the model called. |
| └   `extra_content` | `object` | no | — | Vendor-specific data returned with the tool call, echoed back verbatim. Gemini 3 models reject the turn when `extra_content.google.thought_signature` is missing. |
| └ `tool_call_id` | `string` | no | — | On role "tool" messages: the ID of the tool call this message responds to. |
| └ `reasoning_content` | `string` | no | — | On assistant messages: the reasoning the model returned with that turn, echoed back verbatim. Kimi models expect it on every earlier assistant turn, tool-call turns included, to keep their reasoning across the conversation. |
| `temperature` | `number` | no | — | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. · 0–2 · e.g. `0.8` |
| `max_completion_tokens` | `number` | no | — | An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. |
| `reasoning_effort` | `string` | no | — | Constrains effort on reasoning for reasoning models. Only applicable for o-series models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. NOT supported together with function tools for the gpt-5.6 family (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna) on this endpoint: such requests are rejected by the provider. · Options: `low`, `medium`, `high` |
| `tool_choice` | `ToolChoiceParam \| object` | no | — | Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. |
| `tools` | `FunctionTool[]` | no | — | A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported. |
| └ `name` | `string` | no | — | The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. |
| └ `description` | `string` | no | — | A description of what the function does, used by the model to choose when and how to call the function. |
| └ `parameters` | `object` | no | — | The parameters the functions accepts, described as a JSON Schema object. |
| └ `strict` | `boolean` | no | `false` | Whether to enable strict schema adherence when generating the function call. |
| └ `type` | `string` | yes | `function` | — |
| `service_tier` | `string` | no | — | Specifies the processing type used for serving the request.  · Options: `auto`, `flex`, `priority`, `default` |

### Example request body

```json
{
  "params": {
    "model": "gpt-6-astra",
    "messages": [
      {
        "role": "developer",
        "content": []
      }
    ]
  }
}
```

### Usage examples

#### TypeScript (`ai.apis.run`)

```typescript
import { createClient, ApiRunMode } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

// Calls the 'chat-completions' workflow directly — params are sent as-is.
const { result, usage } = await ai.apis.run('chat-completions', {
  model: "gpt-6-astra",
  messages: [
    {
      role: "developer",
      content: []
    }
  ]
}, {
  mode: ApiRunMode.SYNC,
});

console.log(result); // workflow-specific output
console.log(usage?.credits); // amount charged, in $
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/chat-completions/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "model": "gpt-6-astra",
    "messages": [
      {
        "role": "developer",
        "content": []
      }
    ]
  }
}'
```

### Response

Over HTTP the vendor-shaped result arrives inside the gateway envelope at `response.result`:

```json
{
  "status": "success",
  "response": {
    "id": "wf_abc123",
    "status": "COMPLETED",
    "result": {
      "id": "wf_abc123",
      "created": 0,
      "model": "gpt-6-astra",
      "choices": [
        {
          "index": 0,
          "message": {},
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0,
        "cache_creation_input_tokens": 0,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 0,
          "ephemeral_1h_input_tokens": 0
        },
        "prompt_tokens_details": {
          "cached_tokens": 0,
          "audio_tokens": 0
        },
        "completion_tokens_details": {
          "reasoning_tokens": 0,
          "audio_tokens": 0,
          "accepted_prediction_tokens": 0,
          "rejected_prediction_tokens": 0
        },
        "credits": 0
      }
    }
  }
}
```

`ai.apis.run()` unwraps that envelope and resolves to `{ result, usage }`:

```json
{
  "result": {
    "id": "wf_abc123",
    "created": 0,
    "model": "gpt-6-astra",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "…",
          "content": "…",
          "tool_calls": [],
          "reasoning_content": "…"
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0,
      "cache_creation_input_tokens": 0,
      "cache_creation": {
        "ephemeral_5m_input_tokens": 0,
        "ephemeral_1h_input_tokens": 0
      },
      "prompt_tokens_details": {
        "cached_tokens": 0,
        "audio_tokens": 0
      },
      "completion_tokens_details": {
        "reasoning_tokens": 0,
        "audio_tokens": 0,
        "accepted_prediction_tokens": 0,
        "rejected_prediction_tokens": 0
      },
      "credits": 0
    }
  }
}
```

## Additional resources

- Model page: https://picsart.com/api-platform/models/gemini-2.5-flash
- Try it: https://picsart.com/api-platform/models/gemini-2.5-flash/playground
- SDK: https://picsart.com/api-platform/models/gemini-2.5-flash/sdk
- REST API (unified): https://picsart.com/api-platform/models/gemini-2.5-flash/api
- Compatibility API (vendor parameters): https://picsart.com/api-platform/models/gemini-2.5-flash/advanced
- Pricing: https://picsart.com/api-platform/models/gemini-2.5-flash/pricing
- This document: https://picsart.com/api-platform/models/gemini-2.5-flash/llms.txt
- All models: https://picsart.com/api-platform/models
- Docs — quickstart https://picsart.com/api-platform/docs/quickstart, authentication https://picsart.com/api-platform/docs/authentication, SDK https://picsart.com/api-platform/docs/sdk, REST https://picsart.com/api-platform/docs/api-reference, CLI https://picsart.com/api-platform/docs/cli, MCP https://picsart.com/api-platform/docs/mcp
- CLI reference: https://picsart.github.io/picsart-mcp-cli-docs/guide/introduction