> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neosantara.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Generasi Gambar

> Sintesis gambar berkualitas tinggi dari deskripsi teks via /v1/images/generations.

Endpoint `/v1/images/generations` menyediakan paritas penuh dengan OpenAI Images API untuk menghasilkan gambar dari prompt teks.

```python Python (OpenAI SDK) icon="python" theme={"theme":{"light":"catppuccin-latte","dark":"ayu-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.neosantara.xyz/v1",
    api_key=os.environ["NEOSANTARA_API_KEY"]
)

response = client.images.generate(
    model="imagen-4.0-fast",
    prompt="Pemandangan sawah terasering di Ubud Bali saat matahari terbit, fotorealistik.",
    size="1024x1024",
    n=1
)

image_url = response.data[0].url
print(f"URL Gambar: {image_url}")
```

```javascript Node.js (OpenAI SDK) icon="js" theme={"theme":{"light":"catppuccin-latte","dark":"ayu-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.neosantara.xyz/v1",
  apiKey: process.env.NEOSANTARA_API_KEY,
});

const response = await client.images.generate({
  model: "imagen-4.0-fast",
  prompt: "Pemandangan sawah terasering di Ubud Bali saat matahari terbit, fotorealistik.",
  size: "1024x1024",
  n: 1,
});

console.log("URL Gambar:", response.data[0].url);
```

```bash cURL icon="terminal" theme={"theme":{"light":"catppuccin-latte","dark":"ayu-dark"}}
curl -X POST https://api.neosantara.xyz/v1/images/generations \
  -H "Authorization: Bearer $NEOSANTARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "prompt": "Pemandangan sawah terasering di Ubud Bali.",
    "size": "1024x1024",
    "n": 1
  }'
```

## Parameter Permintaan

| Parameter | Tipe | Wajib | Keterangan |
| :- | :- | :- | :- |
| `prompt` | `string` | Ya | Deskripsi teks visual gambar yang ingin dibuat. |
| `model` | `string` | Ya | Pengidentifikasi model (contoh: `imagen-4.0-fast`, `titan-image-g1`). |
| `size` | `string` | Opsional | Dimensi gambar (contoh: `1024x1024`, `512x512`). Default `1024x1024`. |
| `n` | `integer` | Opsional | Jumlah variasi gambar yang dihasilkan (1 sampai 4). Default `1`. |
| `response_format` | `string` | Opsional | Format keluaran: `"url"` atau `"b64_json"`. Default `"url"`. |

## Arsitektur Teknis & Caching

* **Sinkron vs Asinkron**: Endpoint standar `/v1/images/generations` dirancang untuk integrasi langsung waktu nyata. Untuk proses batch atau model resolusi tinggi, gunakan [Responses API](https://docs.neosantara.xyz/id/gateway/responses-api.md) dengan parameter `background: true` untuk menghindari HTTP timeout.
* **CDN Ephemeral & TTL Caching**: Gambar yang dihasilkan disajikan melalui CDN berkecepatan tinggi dengan URL bertanda tangan sementara. Tautan berlaku selama **5 menit** (TTL). Unduh gambar ke storage permanen (S3/GCS/R2) jika membutuhkan retensi jangka panjang.
* **Perlindungan SSRF**: Saat menyediakan URL gambar input untuk tugas manipulasi/inpainting, gateway memvalidasi rentang IP publik dan memblokir alamat loopback serta jaringan privat untuk mencegah *Server-Side Request Forgery* (SSRF).
* **Penagihan Rupiah**: Biaya generasi gambar dihitung per unit gambar yang berhasil dibuat (*per-image pricing*), bukan berdasarkan token. Biaya langsung didebet dari saldo deposit Rupiah Anda.

## Galeri Hasil Gambar

Berikut contoh output visual yang dihasilkan melalui Neosantara API:

### Generasi Cepat (Fast Inference)

**Model**: `imagen-4.0-fast`

![Hasil generasi gambar Imagen 4.0 Fast](https://mintcdn.com/neosantara/uq2XlSQ_dSPDIOXL/images/showcase-imagen.png?fit=max\&auto=format\&n=uq2XlSQ_dSPDIOXL\&q=85\&s=43447f08eedeefd471665b5be062ef0c)

Prompt: 'Lukisan digital laboratorium berteknologi tinggi di Jakarta, pencahayaan neon, desain futuristik, sangat detail.'

### Artistik & Fantasi

**Model**: `sdxl-lightning`

![Hasil generasi gambar artistik SDXL Lightning](https://mintcdn.com/neosantara/uq2XlSQ_dSPDIOXL/images/showcase-artistic.png?fit=max\&auto=format\&n=uq2XlSQ_dSPDIOXL\&q=85\&s=af48e6100f66ad2de9e171b21fae5759)

Prompt: 'Candi megah di atas awan, pencahayaan etereal, gaya seni fantasi, resolusi tinggi.'

### Fotografi Realistis

**Model**: `titan-image-g1`

![Hasil fotografi realistis Titan Image G1](https://mintcdn.com/neosantara/uq2XlSQ_dSPDIOXL/images/showcase-titan-base.png?fit=max\&auto=format\&n=uq2XlSQ_dSPDIOXL\&q=85\&s=c4bf3ea5d76fad12e98add5e77b5a68f)

Prompt: 'Foto realistis detail tinggi penari tradisional Bali saat malam hari, pencahayaan panggung dramatis.'

### Transformasi Gambar (Image-to-Image)

**Model**: `stable-diffusion-v1-5-img2img`

Mengubah gambar referensi ke gaya visual baru dengan tetap mempertahankan komposisi dasarnya.

> [card] Gambar Asli
>
> Gambar input penari tradisional Bali.

> [card] Transformasi Sketsa
>
> Hasil transformasi gaya sketsa arang artistik.

## Model Generasi Gambar yang Tersedia

| Model ID | Provider | Context Window | Capabilities | Pricing (Input/Output per 1M) |
| :- | :- | :- | :- | :- |
| `agnes-image-2.0-flash` | Agnes AI | N/A | Image Gen | Free / Included |
| `agnes-image-2.1-flash` | Agnes AI | N/A | Image Gen | Free / Included |
| `agnes-image-2.5-flash` | Agnes AI | N/A | Image Gen | Free / Included |
| `imagen-4.0-fast` | Google | N/A | Image Gen | \$0.02/img |
| `neosantara-gen-2045` | Neosantara | N/A | Image Gen | Rp 1,500/img |
| `gpt-image-2` | OpenAI | N/A | Image Gen | \$0.04/img |
| `sdxl-lightning` | Stability AI | N/A | Image Gen | Rp 200/img |
| `stable-diffusion-v1-5-img2img` | Stability AI | N/A | Image Gen | Rp 200/img |
| `grok-imagine-image` | xAI | N/A | Image Gen | \$0.02/img |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.