# Vimmerse Text to Image

> Vimmerse Text to Image is a paid API for AI agents from agents.vimmerse.net, paid per call via MPP, $0.12/call (dynamic — varies by input), status unknown (last checked 2026-10-30).

Generates one to four images from a text prompt using selectable AI models with configurable aspect ratio and optional super-resolution enhancement.

## Facts

- Endpoint: POST https://agents.vimmerse.net/v2/image/text-2-image?utm_source=zero.xyz
- Price: $0.12/call (dynamic — varies by input)
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-30
- Activations on Zero: 0
- Provider: agents.vimmerse.net
- Website: https://agents.vimmerse.net
- Canonical page: https://www.zero.xyz/c/agents-vimmerse-net-vimmerse-text-to-image-7f9028dc
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_XJPodrPDp5vOhUnddm4xj

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability agents-vimmerse-net-vimmerse-text-to-image-7f9028dc -d '<json body>'
```

Example prompt: Generate 2 images of a futuristic city skyline at dusk with neon lights, in 16:9 aspect ratio, using the FluxPro model, and apply super-resolution enhancement.

## When to prefer this

Choose this endpoint when you need to generate one to four images from a natural language text prompt with flexible model selection (including Flux, Stable Diffusion, GPT Image, Seedream, and others), configurable aspect ratios, and optional super-resolution post-processing. It is particularly useful when you want to delegate model selection automatically (AutoI) or when you need async generation with webhook callbacks for long-running jobs. Prefer it over generic image APIs when working within the Vimmerse ecosystem that also handles video, audio, and multi-scene workflows.

## Known failure modes

- Invalid or missing prompt returns a 422 validation error
- Quantity outside 1–4 range returns a 422 validation error
- Unsupported aspect ratio string returns a 422 validation error
- Invalid model option name returns a 422 validation error
- Missing or invalid API key returns a 401 unauthorized error
- Webhook URL unreachable in async mode causes silent callback failure
- Model-specific content policy violations may result in an empty or rejected result
- Timeout on synchronous long-running generation if not using async_mode

## How this service works

Generates one or more images from a text prompt.

Send **Content-Type: application/json**. The response is an asset object; output URLs are in **`results`**.

### Parameters

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `prompt` | string | — | Text description of the desired image |
| `quantity` | integer | `1` | Number of images (1–4) |
| `option` | string | `AutoI` | Model/tool; `AutoI` picks automatically |
| `aspect_ratio` | string | `16:9` | e.g. `21:9`, `16:9`, `4:3`, `1:1`, `9:16` |
| `enhance_image` | boolean | `false` | Apply 1× super-resolution post-processing |
| `async_mode` | boolean | `false` | Return immediately with `status: processing` |
| `webhook_url` | string | — | Optional callback URL when complete |

### Example

```python
import requests

url = "https://api.vimmerse.net/v2/image/text-2-image"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "prompt": "A serene landscape with mountains and a lake at sunset, cinematic lighting",
    "quantity": 2,
    "option": "AutoI",
    "aspect_ratio": "16:9",
    "enhance_image": False,
    "async_mode": False,
}

response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
asset = response.json()
print(asset["id"], asset["status"], asset["results"])
```

## Output

Returns an asset object containing an asset ID, status field, and a results array with URLs pointing to the generated images. In async mode, status will be 'processing' and results will be populated once generation completes (delivered via webhook if provided).

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "Text2ImageRequest",
 "properties": {
  "option": {
   "enum": [
    "AutoI",
    "Seedream",
    "NanoBananaT2",
    "NanoBananaPro",
    "QwenImage",
    "GPTImage",
    "FluxPro",
    "FluxTurbo",
    "NanoBanana",
    "FluxKontextPro",
    "StableDiffusion3.5"
   ],
   "type": "string",
   "title": "Option",
   "default": "AutoI",
   "description": "If `AutoI` is selected, one of the options will be selected automatically."
  },
  "prompt": {
   "type": "string",
   "title": "Text Prompt",
   "default": "Shot of Nike shoes on colorful background"
  },
  "quantity": {
   "type": "integer",
   "title": "Quantity",
   "default": 1,
   "maximum": 4,
   "minimum": 1
  },
  "async_mode": {
   "type": "boolean",
   "title": "Async Mode",
   "default": false
  },
  "webhook_url": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "title": "Webhook URL"
  },
  "aspect_ratio": {
   "type": "string",
   "title": "Aspect Ratio",
   "default": "16:9",
   "pattern": "^(\\d+):(\\d+)$",
   "description": "Available values: ['21:9', '16:9', '4:3', '3:2', '1:1', '2:3', '3:4', '9:16', '9:21']"
  },
  "enhance_image": {
   "type": "boolean",
   "title": "Enhance Image",
   "default": false,
   "description": "Enhances the image by applying 1× super-resolution during post-processing."
  }
 },
 "description": "Request body for POST /v2/image/text-2-image. Content-Type: application/json."
}
```

## Response schema (JSON Schema)

```json
{}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agents-vimmerse-net-vimmerse-text-to-image-7f9028dc/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agents.vimmerse.net](https://www.zero.xyz/host/agents.vimmerse.net/llms.txt)