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

# reve-2-1

> API usage guide for reve-2-1.

{/* source_model_id: reve-2-1 */}

{/* source_updated_at: 1784241469 */}

**Model ID**

```bash theme={null}
reve-2-1
```

**Calling method:** sync

# reve-2-1 API Usage Guide

## Overview

**reve-2-1** is Reve AI's unified v2 image model. A single endpoint covers text-to-image generation, single-image editing, and multi-image remixing — which workflow runs is determined by how many reference images are included in the request. Output resolution is significantly higher than Reve's prior v1 models, and every response includes a structured layout describing the generated regions.

## Authentication

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Submit Image Generation Request

### Endpoint

```
POST /api/v1/ie/requestqueue/apikey/requests
```

### Request Format — text-to-image (no reference images)

```bash theme={null}
curl -X POST "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "reve-2-1",
    "payload": {
      "prompt": "A serene mountain landscape at sunset",
      "aspect_ratio": "16:9"
    }
  }'
```

### Request Format — single-image edit

Pass one URL in `reference_image`. The prompt is treated as a plain edit instruction — no special syntax needed.

```bash theme={null}
curl -X POST "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "reve-2-1",
    "payload": {
      "prompt": "make the background bright blue",
      "reference_image": "https://example.com/photo.jpg"
    }
  }'
```

### Request Format — multi-image remix

Pass 2-8 URLs in `reference_images`. Reference each one from the prompt by position, 0-based: `<frame>0</frame>`, `<frame>1</frame>`, etc.

```bash theme={null}
curl -X POST "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "reve-2-1",
    "payload": {
      "prompt": "combine the subject from <frame>0</frame> with the background from <frame>1</frame>",
      "reference_images": ["https://example.com/a.jpg", "https://example.com/b.jpg"]
    }
  }'
```

### Request Parameters

| Parameter                   | Type                  | Required | Description                                                                                            | Default  |
| --------------------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------ | -------- |
| `model`                     | string                | Yes      | Model identifier                                                                                       | -        |
| `payload.prompt`            | string                | Yes      | Text description, or edit/remix instruction. Max 4000 characters                                       | -        |
| `payload.reference_image`   | string (URL)          | No       | Single image to edit (max 1)                                                                           | -        |
| `payload.reference_images`  | array of string (URL) | No       | 1-8 ordered images to remix                                                                            | -        |
| `payload.aspect_ratio`      | string (enum)         | No       | One of `4:1, 3:1, 21:9, 2:1, 17:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16, 1:2, 1:3, 1:4, auto` | `"auto"` |
| `payload.postprocessing`    | array                 | No       | Operations applied after generation — see Postprocessing below                                         | none     |
| `payload.test_time_scaling` | integer               | No       | Spend more compute for a better image (1-15). Higher values cost more credits                          | `1`      |
| `payload.breadcrumb`        | string                | No       | Request-tracking tag, searchable in Reve's own Usage page                                              | -        |

### Postprocessing

`payload.postprocessing` is a list of operations, applied in order:

* `{"process": "upscale", "upscale_factor": 2}` — factor 1-4
* `{"process": "remove_background"}` — makes the background transparent
* `{"process": "fit_image", "max_dim": 512}` — resize to fit (use `max_dim`, `max_width`, or `max_height`); no extra cost
* `{"process": "effect", "effect_name": "grain"}` — apply a named effect preset configured in the Reve app

All operations except `fit_image` add a small amount of extra credit cost.

### Response

```json theme={null}
{
  "request_id": "cd5b59d5-1b3f-4fd5-9899-15ecea1f28ba",
  "model": "reve-2-1",
  "status": "success",
  "outcome": {
    "media_urls": [{"id": "0", "url": "https://storage.googleapis.com/..."}],
    "thumbnail_image_url": "https://storage.googleapis.com/...",
    "credits_used": 150,
    "credits_remaining": 264636,
    "model_version": "reve-v2-create@260601"
  }
}
```

## Pricing

Reve bills in **credits**, not tokens or time. Verified 2026-07-14 by measuring the live API directly: text-to-image, single-image edit, and multi-image remix all consume the same flat **150 credits** per call. `postprocessing` and `test_time_scaling` add credits on top of that baseline.

### Credit Pricing

| Operation                                      | Credits                                      |
| ---------------------------------------------- | -------------------------------------------- |
| Base generation (any of create / edit / remix) | 150                                          |
| `postprocessing: fit_image`                    | +0                                           |
| `postprocessing: upscale`                      | +1                                           |
| `postprocessing: remove_background`            | +2                                           |
| `postprocessing: effect`                       | +3                                           |
| `test_time_scaling`                            | scales linearly (value 5 → 5x total credits) |

Conversion rate: \~1333.33 micro-USD per credit, so the 150-credit baseline is \*\*$0.20 per image**. This rate is derived from the pricing of Reve's earlier v1 models (consistent across all 5 existing v1 price entries) since Reve's own pricing page is a JS-rendered app that can't be fetched programmatically; independently cross-checked against a third-party pricing writeup ($10/7500 credits ≈ $1.33/1000 credits — the same rate) and against the measured 150-credit baseline (both sources agree the result is ~$0.20/image).

## Check Request Status

```
GET /api/v1/ie/requestqueue/apikey/requests/{request_id}
```