Reve API - Docs

Documentation Overview

The Reve API enables you to generate, edit, and remix high-quality images. To learn more about the pricing for our endpoints, visit the pricing page.

Endpoints

The Reve API provides the following endpoints for different image generation workflows:

POST https://api.reve.com/v2/image/create

Generate images from text with optional ordered reference images. Returns a description layout alongside the image.

Read documentation →

GET https://api.reve.com/v1/image/effect

List the effects available to the project associated with the API token, including saved project effects and built-in presets.

These are experimental layout building blocks that require care and experimentation to achieve good results. For the easiest, "batteries included" workflow, prefer the Create endpoint above.

POST https://api.reve.com/v2/image/extract_layout

Extract a structured layout from an image, optionally guided by a prompt. An experimental building block for layout-driven workflows.

Read documentation →

POST https://api.reve.com/v2/image/create_layout

Generate a structured layout from a text prompt and optional reference images, without rendering an image. An experimental building block for precise composition control.

Read documentation →

POST https://api.reve.com/v2/image/render_layout

Render a final image from a structured layout. An experimental building block that pairs with Create Layout.

Read documentation →

POST https://api.reve.com/v1/image/create

Generate images from text descriptions. Perfect for creating original artwork, illustrations, and visual content from your imagination.

Read documentation →

POST https://api.reve.com/v1/image/edit

Modify existing images using text instructions. Upload an image and describe the changes you want to make.

Read documentation →

POST https://api.reve.com/v1/image/remix

Combine text prompts with reference images to create new variations. Blend styles, concepts, and visual elements.

Read documentation →

Quickstart

cURL

curl -X POST https://api.reve.com/v2/image/create \
  -H "Authorization: Bearer $REVE_API_KEY" \
  -H "Accept: image/webp" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over mountains"
  }' -o mountain.webp

Response Formats

All API endpoints support multiple response formats based on the Accept header:

application/json (default) - Returns a JSON response with the image base64 encoded in PNG format, and metadata. This is the default format.
image/png - Returns the generated image directly as bytes in PNG format. Metadata will be provided through the custom headers.
image/jpeg - Returns the generated image directly as bytes in JPEG format. Metadata will be provided through the custom headers.
image/webp - Returns the generated image directly as bytes in WebP format. Metadata will be provided through the custom headers.

Response Codes

The API uses standard HTTP status codes to indicate the success or failure of requests. They include, but are not limited to:

200 Request was successful
400 Bad request - Invalid parameters or malformed request
401 Unauthorized - Invalid or missing API key
402 Insufficient credits - Your budget has run out
404 Not found - Endpoint or resource does not exist
422 Unprocessable content - The inputs could not be understood
429 Rate limit exceeded - Too many requests in a short period
500 Internal server error - Something went wrong on our end

Response Headers

All API responses include standard headers that provide additional information about the request and response:

X-Reve-Content-Violation - Indicates whether the generated image violates the content policy. true if there is a violation, false if there isn't. Any 200 status response.
X-Reve-Request-Id - A unique identifier for the request. Use this when contacting support about specific requests. Every request.
X-Reve-Version - The specific model version used in the generation process. For example, reve-edit@20250915. 200 status responses when Accept header is an image type.
X-Reve-Credits-Used - The number of credits used for this request. 200 status responses when Accept header is an image type.
X-Reve-Credits-Remaining - The number of credits remaining in your budget after this request. 200 status responses when Accept header is an image type.
X-Reve-Error-Code - The type of error that occurred. Could be strings like PROMPT_TOO_LONG, CONTENT_POLICY_VIOLATION, etc. All non-200 status responses, and 200 status responses where there is a content policy violation.

Supported input image formats

When providing images to the Reve API, we support the following formats, base64-encoded as inline JSON data. A single image may be at most 40 MB and 33,554,432 pixels (for example 8192x4096), with neither dimension exceeding 8192 pixels. A single call may include at most 50,331,648 pixels and 100 MB of image data (after base64 decoding).

WEBP
JPEG
PNG
GIF
TIFF (the most common flavors)
AVIF (the most common flavors)

v2 Aspect Ratios

The v2 image and layout endpoints accept the full unified-model aspect-ratio set, including auto. The v1 endpoints intentionally document and accept only the smaller legacy subset.

v2 allowed aspect ratios: 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.
v1 allowed aspect ratios: 16:9, 3:2, 4:3, 1:1, 3:4, 2:3, 9:16.
Use auto to let v2 choose an appropriate aspect ratio for the request.

v2 Latency and Client Timeouts

v2 endpoints perform model inference synchronously, so requests can run longer than many default HTTP client timeouts. Configure clients, load balancers, proxies, and job runners with request timeouts of at least 120 seconds.

Layout generation and layout editing endpoints commonly take 10–40 seconds.
Image generation, image editing, and layout rendering endpoints commonly take 40–80 seconds.
Treat shorter client-side timeouts as cancellations: the server may still finish the request after the client disconnects.

Request Tracking with Breadcrumbs

You can add an optional &breadcrumb= query parameter to any API request to help track and identify requests in your logs. This is useful for correlating API requests with client-side actions or debugging specific workflows.

Example

https://api.reve.com/v1/image/create?breadcrumb=my-workflow-step-1

The breadcrumb value is stored with the request and can be searched in the Usage page.
Breadcrumbs are not required to be unique - you can use the same breadcrumb for multiple related requests.
The breadcrumb parameter is ignored by the API and does not affect the request processing.

Test Time Scaling

You can optionally spend more time making better images by setting the test_time_scaling parameter to a value between 1 and 5. Any value above 1 will add additional API credits cost to the request.

Example

"test_time_scaling": 3,

The default value is 1.
The maximum value is 15.
Values above 15 will be clamped to 15.
Values below 1 will be clamped to 1.
We currently do not recommend enabling test_time_scaling for v2 models.

Postprocessing: Upscale

You can optionally upscale the generated image by setting the postprocessing parameter to include an upscale object with the desired upscale factor.

Example

"postprocessing": [{ "process": "upscale", "upscale_factor": 2 }]

The upscale factor must be an integer between 1 and 4.
The default upscale factor is 1 (no upscale).
Upscaling will add additional API credits cost to the request.

Postprocessing: Remove Background

You can optionally remove the background from the generated image by setting the postprocessing parameter to include a remove_background object.

Example

"postprocessing": [{ "process": "remove_background" }]

Removing the background will add additional API credits cost to the request.
Removing the background will not work well on images without a clear subject.

Postprocessing: Fit Image

You can optionally resize the generated image to fit within specified dimensions by setting the postprocessing parameter to include a fit_image object. The image will be scaled down while preserving its aspect ratio.

Example

"postprocessing": [{ "process": "fit_image", "max_dim": 512 }]

At least one of max_dim, max_width, or max_height must be specified.
max_dim constrains the longest side of the image.
max_width constrains only the width of the image.
max_height constrains only the height of the image.
The maximum value for each parameter is 4096.
This operation has no additional API credits cost.
Images smaller than the specified dimensions will not be enlarged.

Postprocessing: Effect

You can optionally apply a saved effect to the generated image by setting the postprocessing parameter to include an effect object. The effect must be saved in the project associated with your API key.

Example

"postprocessing": [{ "process": "effect", "effect_name": "my-effect" }]

The effect_name must match an effect saved in the project.
The effect list returns preset names, not effect parameter definitions. Configure effect presets in the main application, save them with a name, and apply that saved name from the API.
You can optionally override effect parameters using the effect_parameters field.
Parameter overrides use the format: { filterId: { uniformId: value } }.
Missing parameters use the effect's saved defaults.
Effects are configured in the Reve application and linked to your project.

Listing Available Effects

Use GET /v1/image/effect to list all effects available to the project associated with your API token. The default response includes saved project effects and built-in presets, so the returned name values can be used as effect_name in postprocessing requests.

Field Type Description

effects (array) - All available effect presets for the API token's project; parameter definitions are not included.
effects[].name (string) - Effect name to pass as postprocessing.effect_name.
effects[].source (string) - saved for project effects, builtin for system presets.
effects[].description (string, optional) - Optional human-readable effect description.
effects[].category (string, optional) - Optional preset category, such as color or texture.
The response is a JSON object with an effects array.
Each effect has name and source fields. description and category are included when available.
Effect parameters are not included in the list response. Use saved preset names from the main application as effect_name values in API postprocessing requests.
source is saved for project effects and builtin for system presets.
The optional source query parameter can be all, project, or preset; all is the default.

List effects

JSON

{
  "effects": [
    {
      "name": "cmyk_halftone",
      "description": "CMYK halftone print effect",
      "source": "builtin",
      "category": "textures"
    },
    {
      "name": "my-saved-effect",
      "source": "saved"
    }
  ]
}

v2 Reference Shapes

The references field has different shapes for the high-level image endpoints and the layout pipeline endpoints. Use raw image objects for v2/image/create. Use compound { image, layout, prompt } reference objects for layout generation and rendering endpoints.

v2/image/create references are raw image objects: each item has exactly one of data or ref.
v2/image/create returns a layout, but its input references do not include layouts.
v2/image/create_layout and v2/image/render_layout references may include an image, layout, prompt, or any combination.
Layout-only render references provide structure, but cannot be targeted as image pixels.

Layouts

A layout describes the composition of an image as a set of labeled regions, giving you precise control over what appears where. It is a JSON object with an optional overall prompt and a required regions array. Each region carries a label, a regional prompt, and a normalized bbox; the remaining fields are optional. Keep prompts concise — short noun phrases such as a red hat usually work better than long sentences, and the layout-level prompt is the place for any broader, whole-image description.

Example

{ "prompt": "a person at a cafe", "regions": [{ "label": "person", "prompt": "a woman in a red coat", "bbox": { "x0": 0.1, "y0": 0.1, "x1": 0.6, "y1": 0.9 } }] }

prompt (layout, optional): an overall prompt describing the whole image.
regions (layout, required): the array of regions that make up the layout.
label (region, required): a short entity name, unique within the layout.
prompt (region, required): the regional prompt; concise phrases work best.
bbox (region, required): the region's bounding box, normalized to [0, 1] with a top-left origin.
image_index (region, optional): zero-based index into the input images this region refers to.
image_region_index (region, optional): zero-based index of the corresponding region within the referenced image's layout.
parent (region, optional): the label of this region's parent region, establishing a containment hierarchy.
region_type (region, optional): a level-of-detail and special-handling hint. coarse_detail marks a high-level object, such as a person or a car; medium_detail marks a medium object, such as an arm, a belt, or a wheel, whose parent is a coarse_detail region; fine_detail marks a fine detail, such as a ring, a buckle, or a lug nut, whose parent is a medium_detail region; text marks a region of text embedded into the image; hand and face are special kinds for human hands and faces. Omit to let the model choose.
image_index and image_region_index are zero-based. In the edit endpoint, the base image is image 0 and each additional reference image is image 1 … N.
We charge for every attempted generation, including attempts we reject for violating our Terms of Service.

Layout Commands

The create_layout endpoint accepts an optional commands array of ordered, imperative edits applied on top of the prompt and references. Each command has an op plus op-specific fields. Positions (at, to) are either a normalized bounding box { x0, y0, x1, y1 } or a normalized point { x, y }, with coordinates in [0, 1] and a top-left origin. Fields marked with a trailing ? are optional. The valid shapes for each command are:

add

Introduce a new subject, optionally positioned.

{ "op": "add", "label": string } { "op": "add", "description": string } { "op": "add", "label": string, "at": { "x0", "y0", "x1", "y1" } } { "op": "add", "label": string, "at": { "x", "y" } } { "op": "add", "description": string, "at": { "x0", "y0", "x1", "y1" } } { "op": "add", "description": string, "at": { "x", "y" } }

place

Add a subject at a required position.

{ "op": "place", "label": string, "at": { "x0", "y0", "x1", "y1" } } { "op": "place", "label": string, "at": { "x", "y" } } { "op": "place", "description": string, "at": { "x0", "y0", "x1", "y1" } } { "op": "place", "description": string, "at": { "x", "y" } }

shift

Move a subject to a required destination, optionally from a specific image.

{ "op": "shift", "label": string, "to": { "x0", "y0", "x1", "y1" }, "at"?: {…}, "image_index"?: number } { "op": "shift", "label": string, "to": { "x", "y" }, "at"?: {…}, "image_index"?: number } { "op": "shift", "description": string, "to": { "x0", "y0", "x1", "y1" }, "at"?: {…}, "image_index"?: number } { "op": "shift", "description": string, "to": { "x", "y" }, "at"?: {…}, "image_index"?: number }

remove

Remove a subject, optionally scoped to a position or image.

{ "op": "remove", "label": string, "at"?: {…}, "image_index"?: number } { "op": "remove", "description": string, "at"?: {…}, "image_index"?: number }

keep

Preserve a subject; subject is optional.

{ "op": "keep", "at"?: {…}, "image_index"?: number } { "op": "keep", "label": string, "at"?: {…}, "image_index"?: number } { "op": "keep", "description": string, "at"?: {…}, "image_index"?: number }

change

Rewrite a labeled region's description in place.

{ "op": "change", "label": string, "new_description": string }