> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creatify.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Generate text with Gemini models — supports synchronous, asynchronous, and streaming modes. Send messages and get the result directly, poll / receive a webhook, or stream tokens in real time via SSE.
## 🚀 Introduction
The **Text Generator API** lets you run **text generation** with Gemini models.
It supports three modes:
* **Sync mode** (`sync: true`): The request blocks until generation completes and returns the result directly.
* **Async mode** (default): The request returns immediately with a `pending` status. Poll or receive a webhook when the result is ready.
* **Streaming mode** (SSE): Tokens are streamed back in real time via Server-Sent Events.
***
## ✅ Prerequisites
* A Creatify account with **API access**
* Your **API credentials** (see [Authentication](/api-reference/authentication))
***
## Supported Models
| Model Name |
| ------------------------------- |
| `gemini-2.5-flash` |
| `gemini-2.5-pro` |
| `gemini-3-flash-preview` |
| `gemini-3.1-pro-preview` |
| `gemini-3.1-flash-lite-preview` |
***
## 1) Create a Text Generation Task
Send `model_name`, `messages`, and optional parameters like `system_instruction`, `config`, and `webhook_url`.
**Endpoint:** [POST /sse/text\_generator/](/api-reference/text-generator/post-text-generator-hp)
**Body:**
* `model_name` (string, required) — Name of the Gemini model (e.g. `gemini-2.5-flash`)
* `messages` (array, required) — List of message objects with `role` (`user` or `model`) and `content`
* `system_instruction` (string, optional) — System instruction for the model
* `config` (object, optional) — Generation config parameters (temperature, max\_output\_tokens, etc.)
* `webhook_url` (string URL, optional) — Webhook URL for async status updates
* `sync` (boolean, optional, default: `false`) — If `true`, the request blocks until generation completes and returns the result directly
### Async Mode (default)
```bash Example Request theme={null}
curl --request POST \
--url https://api.creatify.ai/sse/text_generator/ \
--header 'Content-Type: application/json' \
--header 'X-API-ID: your-api-id' \
--header 'X-API-KEY: your-api-key' \
--data '{
"model_name": "gemini-2.5-flash",
"messages": [
{"role": "user", "content": "Write a short tagline for an AI video tool."}
],
"system_instruction": "You are a creative marketing copywriter.",
"config": {
"temperature": 0.8,
"max_output_tokens": 256
},
"webhook_url": "https://webhook.site/your-webhook-id"
}'
```
```json Example Response theme={null}
{
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"model_name": "gemini-2.5-flash",
"messages": [
{"role": "user", "content": "Write a short tagline for an AI video tool."}
],
"system_instruction": "You are a creative marketing copywriter.",
"config": {
"temperature": 0.8,
"max_output_tokens": 256
},
"status": "pending",
"response_text": "",
"response_function_calls": [],
"failed_reason": "",
"credits_used": 0,
"created_at": "2026-03-19T10:00:00.000000-08:00",
"updated_at": "2026-03-19T10:00:00.000000-08:00"
}
```
### Sync Mode
Set `"sync": true` to block until generation completes. The response will contain the final result directly — no polling or webhook needed.
```bash Example Request theme={null}
curl --request POST \
--url https://api.creatify.ai/sse/text_generator/ \
--header 'Content-Type: application/json' \
--header 'X-API-ID: your-api-id' \
--header 'X-API-KEY: your-api-key' \
--data '{
"model_name": "gemini-2.5-flash",
"messages": [
{"role": "user", "content": "Write a short tagline for an AI video tool."}
],
"system_instruction": "You are a creative marketing copywriter.",
"config": {
"temperature": 0.8,
"max_output_tokens": 256
},
"sync": true
}'
```
```json Example Response theme={null}
{
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"model_name": "gemini-2.5-flash",
"messages": [
{"role": "user", "content": "Write a short tagline for an AI video tool."}
],
"system_instruction": "You are a creative marketing copywriter.",
"config": {
"temperature": 0.8,
"max_output_tokens": 256
},
"status": "done",
"response_text": "Create stunning videos in seconds — powered by AI.",
"response_function_calls": [],
"failed_reason": "",
"credits_used": 0.0005,
"created_at": "2026-03-19T10:00:00.000000-08:00",
"updated_at": "2026-03-19T10:00:02.500000-08:00"
}
```
### Config Parameters
| Parameter | Type | Description |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------- |
| `temperature` | float | Controls randomness. Range: 0.0 – 2.0. Lower = more deterministic. |
| `max_output_tokens` | int | Maximum number of tokens to generate. |
| `top_p` | float | Nucleus sampling threshold. Range: 0.0 – 1.0. |
| `top_k` | int | Top-k sampling. Only sample from top k tokens. |
| `presence_penalty` | float | Penalize tokens already present. Range: -2.0 – 2.0. |
| `frequency_penalty` | float | Penalize tokens by frequency. Range: -2.0 – 2.0. |
| `seed` | int | Random seed for deterministic generation. |
| `stop_sequences` | string\[] | List of strings that stop generation when encountered. |
| `response_mime_type` | string | `text/plain` or `application/json`. |
| `response_json_schema` | object | JSON Schema for structured output. Automatically sets `response_mime_type` to `application/json`. |
***
### Multimodal Input (Image / Video)
Messages support multimodal content — send images or videos alongside text by providing a list of content parts. Each part specifies a `type` (`text`, `image`, or `video`) with the corresponding data.
**Limits:** Images up to **20 MB**, videos up to **100 MB**.
Multimodal requests — especially with video — can take significantly longer to process. We recommend using **async mode** (default) with polling or a webhook, rather than sync mode.
**Supported MIME types:**
* Image: `image/jpeg`, `image/png`, `image/gif`, `image/webp`
* Video: `video/mp4`, `video/mpeg`, `video/mov`, `video/avi`, `video/webm`, `video/quicktime`, and more
```bash Example Request (Image) theme={null}
curl --request POST \
--url https://api.creatify.ai/sse/text_generator/ \
--header 'Content-Type: application/json' \
--header 'X-API-ID: your-api-id' \
--header 'X-API-KEY: your-api-key' \
--data '{
"model_name": "gemini-2.5-flash",
"messages": [
{
"role": "user",
"content": [
{"type": "image", "data": "", "mime_type": "image/jpeg"},
{"type": "text", "text": "Describe what you see in this image."}
]
}
],
"webhook_url": "https://webhook.site/your-webhook-id"
}'
```
```bash Example Request (Video) theme={null}
curl --request POST \
--url https://api.creatify.ai/sse/text_generator/ \
--header 'Content-Type: application/json' \
--header 'X-API-ID: your-api-id' \
--header 'X-API-KEY: your-api-key' \
--data '{
"model_name": "gemini-2.5-flash",
"messages": [
{
"role": "user",
"content": [
{"type": "video", "data": "", "mime_type": "video/mp4"},
{"type": "text", "text": "Summarize this video in 3 bullet points."}
]
}
],
"webhook_url": "https://webhook.site/your-webhook-id"
}'
```
```json Example Response theme={null}
{
"id": "b2c3d4e5-6789-01bc-defg-234567890abc",
"model_name": "gemini-2.5-flash",
"status": "pending",
"response_text": "",
"response_function_calls": [],
"credits_used": 0,
"created_at": "2026-03-19T10:00:00.000000-08:00",
"updated_at": "2026-03-19T10:00:00.000000-08:00"
}
```
### Function Calling
Enable the model to call functions you define. Provide `tools` with function declarations and optionally configure calling behavior with `tool_config`.
```bash Example Request theme={null}
curl --request POST \
--url https://api.creatify.ai/sse/text_generator/ \
--header 'Content-Type: application/json' \
--header 'X-API-ID: your-api-id' \
--header 'X-API-KEY: your-api-key' \
--data '{
"model_name": "gemini-2.5-flash",
"messages": [
{"role": "user", "content": "What is the weather in San Francisco?"}
],
"tools": [
{
"function_declarations": [
{
"name": "get_weather",
"description": "Get the current weather for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City name"}
},
"required": ["location"]
}
}
]
}
],
"tool_config": {
"function_calling_config": {
"mode": "AUTO"
}
},
"sync": true
}'
```
```json Example Response (function call) theme={null}
{
"id": "c3d4e5f6-7890-12cd-efgh-345678901bcd",
"model_name": "gemini-2.5-flash",
"status": "done",
"response_text": "",
"response_function_calls": [
{
"name": "get_weather",
"args": {"location": "San Francisco"}
}
],
"credits_used": 0.001,
"created_at": "2026-03-19T10:00:00.000000-08:00",
"updated_at": "2026-03-19T10:00:01.500000-08:00"
}
```
After receiving a function call, you can send the result back in a follow-up message:
```bash Example Request (Function Response) theme={null}
curl --request POST \
--url https://api.creatify.ai/sse/text_generator/ \
--header 'Content-Type: application/json' \
--header 'X-API-ID: your-api-id' \
--header 'X-API-KEY: your-api-key' \
--data '{
"model_name": "gemini-2.5-flash",
"messages": [
{"role": "user", "content": "What is the weather in San Francisco?"},
{"role": "model", "function_call": {"name": "get_weather", "args": {"location": "San Francisco"}}},
{"role": "user", "function_response": {"name": "get_weather", "response": {"temperature": 62, "condition": "Foggy"}}}
],
"tools": [
{
"function_declarations": [
{
"name": "get_weather",
"description": "Get the current weather for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City name"}
},
"required": ["location"]
}
}
]
}
],
"sync": true
}'
```
```json Example Response theme={null}
{
"id": "d4e5f6a7-8901-23de-fghi-456789012cde",
"model_name": "gemini-2.5-flash",
"status": "done",
"response_text": "The weather in San Francisco is currently 62°F and foggy.",
"response_function_calls": [],
"credits_used": 0.001,
"created_at": "2026-03-19T10:00:00.000000-08:00",
"updated_at": "2026-03-19T10:00:01.500000-08:00"
}
```
**Function calling modes:**
| Mode | Description |
| ------ | ----------------------------------------------------------------------- |
| `AUTO` | Model decides whether to call a function or respond with text (default) |
| `ANY` | Model must call one of the provided functions |
| `NONE` | Model will not call any functions |
***
## 2) Streaming Mode (SSE)
For real-time token streaming, use the dedicated SSE endpoint. Tokens are delivered as they are generated — no polling needed.
**Endpoint:** [POST /sse/text\_generator/stream/](/api-reference/text-generator/post-text-generator-streaming)
The request body is the same as the standard endpoint (minus `sync` and `webhook_url`). The response is an SSE stream (`text/event-stream`) of Gemini-native response chunks. The final chunk includes a `creatify` object with the generation `id` and `credits_used`.
```bash Example Request theme={null}
curl --request POST \
--url https://api.creatify.ai/sse/text_generator/stream/ \
--header 'Content-Type: application/json' \
--header 'X-API-ID: your-api-id' \
--header 'X-API-KEY: your-api-key' \
--data '{
"model_name": "gemini-2.5-flash",
"messages": [
{"role": "user", "content": "Write a short tagline for an AI video tool."}
],
"config": {
"temperature": 0.8,
"max_output_tokens": 256
}
}'
```
```text Example Response (SSE stream) theme={null}
data: {"candidates":[{"content":{"parts":[{"text":"Create"}],"role":"model"}}],"model_version":"gemini-2.5-flash"}
data: {"candidates":[{"content":{"parts":[{"text":" stunning videos"}],"role":"model"}}],"model_version":"gemini-2.5-flash"}
data: {"candidates":[{"content":{"parts":[{"text":" in seconds."}],"role":"model"},"finish_reason":"STOP"}],"usage_metadata":{"prompt_token_count":12,"candidates_token_count":8,"total_token_count":20},"model_version":"gemini-2.5-flash","creatify":{"id":"a1b2c3d4-5678-90ab-cdef-1234567890ab","credits_used":0.0005}}
```
The streaming endpoint uses the same authentication (X-API-KEY + X-API-ID) and credit system as the standard endpoint.
***
## 3) Check Status (Poll) or Receive Webhook (Async mode only)
When using async mode (default), you can **poll** the task until `status` is `done`, or provide a **webhook** to be notified automatically. The generated text is in the `response_text` field.
> If you used `"sync": true`, skip this step — the response already contains the completed result.
**Endpoint:** `GET /sse/text_generator/{id}/`
### Poll
```bash Example Request theme={null}
curl --request GET \
--url https://api.creatify.ai/sse/text_generator/a1b2c3d4-5678-90ab-cdef-1234567890ab/ \
--header 'X-API-ID: your-api-id' \
--header 'X-API-KEY: your-api-key'
```
```json Example Response theme={null}
{
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"model_name": "gemini-2.5-flash",
"messages": [
{"role": "user", "content": "Write a short tagline for an AI video tool."}
],
"system_instruction": "You are a creative marketing copywriter.",
"config": {
"temperature": 0.8,
"max_output_tokens": 256
},
"status": "done",
"response_text": "Create stunning videos in seconds — powered by AI.",
"response_function_calls": [],
"failed_reason": "",
"credits_used": 0.0005,
"created_at": "2026-03-19T10:00:00.000000-08:00",
"updated_at": "2026-03-19T10:00:02.500000-08:00"
}
```
### Webhook (Optional)
If you supplied a `webhook_url` when creating the task, we'll POST a payload when it finishes. The generated text is in the `response_text` field.
```json theme={null}
{
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"status": "done",
"response_text": "Create stunning videos in seconds — powered by AI.",
"response_function_calls": [],
"failed_reason": "",
"credits_used": 0.0005
}
```
> You can verify the task any time with a GET to `/sse/text_generator/{id}/`.
***
## Status Values
| Status | Description |
| --------- | ------------------------------------------- |
| `pending` | Task created, waiting to be processed |
| `running` | Model is generating text |
| `done` | Generation complete — check `response_text` |
| `failed` | Generation failed — check `failed_reason` |
***
## 📚 Endpoint Reference
| Action | Endpoint |
| ----------------------------------------- | ---------------------------------- |
| Create a text generation task | `POST /sse/text_generator/` |
| Create a text generation task (streaming) | `POST /sse/text_generator/stream/` |
| List text generation tasks | `GET /sse/text_generator/` |
| Get task status / result | `GET /sse/text_generator/{id}/` |
***
## 🎯 Summary
| Step | What you do |
| ---- | -------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Create a **text generation** task with `model_name` + `messages` (+ optional `config`, `sync`, `webhook_url`) |
| 2a | **Sync mode** (`sync: true`): Result is returned directly in the response — done! |
| 2b | **Async mode** (default): **Poll** `/sse/text_generator/{id}/` or receive a **webhook** with the final result in `response_text` |
| 2c | **Streaming mode**: POST to `/sse/text_generator/stream/` and consume the SSE stream in real time |