> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# Generate image

POST https://api.videogen.io/v1/tools/generate-image
Content-Type: application/json

Generate an image from a text prompt, optionally guided by reference images and actor, product, or visual-style entity ids. When reference images are provided, the prompt describes the desired transformation. VideoGen automatically routes each request to the most effective state-of-the-art image model for your prompt, reference images, entities, and quality tier, so you don't pick a model.

Reference: https://docs.videogen.io/rest-api-reference/tools/generate-image

## Authentication

- `Authorization` header (bearer token, required) — API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

## Request

### Body (application/json)

This endpoint expects a GenerateImageRequest.

- `prompt` (string, required) — Text prompt describing the image to generate. When reference images are provided, the prompt describes the desired transformation.
- `imageFileIds` (list of string, optional) — Optional file ids of reference images (e.g. `["vg_file_..."]`). Upload files first via `POST /v1/files/upload`, then pass the returned ids here. Maximum 4 images. When provided, the model uses these as guidance for generation.
- `entityIds` (list of string, optional) — Optional actor, product, or visual-style entity ids (e.g. `["vg_enti_..."]`). The model uses each entity as identity/reference the same way in-app image generation does. Can be combined with `imageFileIds`. A missing id returns not found; an inaccessible id returns a permission error.
- `aspectRatio` (AspectRatio, optional) — Aspect ratio for the generated image. Defaults to 16:9 when omitted.
- `quality` (enum, optional) — Image generation quality tier. Optional; when omitted, your account's Default AI quality for images is used (change it at https://app.videogen.io/settings/account).
  - Allowed values: `LOW`, `STANDARD`, `HIGH`, `MAX`
- `contentPolicyConfig` (ContentPolicyConfig, optional) — Controls how content-policy rejections are handled during generation.
- `watermarkMode` (enum, optional, default: AUTO) — Controls whether the VideoGen watermark is applied to the output. `AUTO` applies the watermark unless you have a Pro plan. `VIDEO_GEN` always applies it. `NONE` removes the watermark (requires Pro; returns an error if you don't have it).
  - Allowed values: `NONE`, `VIDEO_GEN`, `AUTO`
- `numResults` (integer, optional, default: 1) — Number of output results to generate. Defaults to 1.
- `isOutputTemporary` (boolean, optional, default: false) — When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false.
- `hideFromUi` (boolean, optional, default: false) — When true, generated files are hidden from the VideoGen Media page by default. They remain accessible through the API. Defaults to false.

## Response

### 202

Execution accepted; poll until complete.

- `toolExecutionId` (string, required) — Execution id (e.g. `vg_tool_...`).

## Types

### AspectRatio

Aspect ratio as a width:height pair (e.g. 16 and 9 for 16:9). Not pixel dimensions.

- `width` (integer, required)
- `height` (integer, required)

### ContentPolicyConfig

Controls how content-policy rejections are handled during generation.

- `maxPromptRewrites` (integer, optional, default: 0) — Maximum number of automatic prompt rewrites to attempt after a content-policy rejection before failing. Must be an integer between 0 and 4. 0 (the default) fails on the first rejection and returns the moderation error so you can revise the prompt yourself. Higher values let the request automatically rephrase and retry the prompt.

## Examples

### Example_0

**Request**

```json
{
  "prompt": "A serene mountain landscape at sunrise with vibrant colors and mist",
  "quality": "STANDARD"
}
```

**Response**

```json
{
  "toolExecutionId": "vg_tool_ccm3abc123defcm3xyz789ghi"
}
```

**SDK Code**

```typescript Example_0
import { VideoGen } from "@videogen/sdk";

const client = new VideoGen({ apiKey: "sk_videogen_live_..." });

await client.tools.generateImage({
  prompt: "A serene mountain landscape at sunrise with vibrant colors and mist",
  quality: "STANDARD",
});
```

```python Example_0
from videogen import VideoGen

client = VideoGen(api_key="sk_videogen_live_...")

client.tools.generate_image(
    prompt="A serene mountain landscape at sunrise with vibrant colors and mist",
    quality="STANDARD",
)
```

### Example_1

**Request**

```json
{
  "prompt": "Transform this photo into an oil painting style with warm autumn tones",
  "imageFileIds": [
    "vg_file_obLD1OX2eJCrEs0071Z4kA"
  ],
  "quality": "STANDARD"
}
```

**Response**

```json
{
  "toolExecutionId": "vg_tool_ccm3abc123defcm3xyz789ghi"
}
```

**SDK Code**

```typescript Example_1
import { VideoGen } from "@videogen/sdk";

const client = new VideoGen({ apiKey: "sk_videogen_live_..." });

await client.tools.generateImage({
  prompt: "Transform this photo into an oil painting style with warm autumn tones",
  quality: "STANDARD",
  imageFileIds: [
    "vg_file_obLD1OX2eJCrEs0071Z4kA",
  ],
});
```

```python Example_1
from videogen import VideoGen

client = VideoGen(api_key="sk_videogen_live_...")

client.tools.generate_image(
    prompt="Transform this photo into an oil painting style with warm autumn tones",
    quality="STANDARD",
    image_file_ids=[
      "vg_file_obLD1OX2eJCrEs0071Z4kA",
    ],
)
```