Sign in
Tools

Generate image

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.

post/v1/tools/generate-image

Request body

promptstring required

Text prompt describing the image to generate. When reference images are provided, the prompt describes the desired transformation.

imageFileIdsstring[]

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.

entityIdsstring[]

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.

quality'LOW' | 'STANDARD' | 'HIGH' | 'MAX'

AI generation quality tier, shared across every generative feature (image, video, text, and so on). LOW is fastest and cheapest, STANDARD balances quality and cost, HIGH is higher quality, and MAX is the highest quality.

When a request omits the quality field, VideoGen falls back to your account's Default AI quality for that feature, which you can change at Account settings. Not every feature supports every tier; unsupported tiers are rejected with an error (see each field's description).

watermarkMode'NONE' | 'VIDEO_GEN' | '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).

numResultsinteger

Number of output results to generate. Defaults to 1.

isOutputTemporaryboolean

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.

hideFromUiboolean

When true, generated files are hidden from the VideoGen Media page by default. They remain accessible through the API. Defaults to false.

Example request

{
  "prompt": "A serene Japanese garden with cherry blossoms at golden hour"
}

Response

Execution accepted; poll until complete.

toolExecutionIdstring required

Execution id (e.g. vg_tool_...).

Changes

No recorded changes to this endpoint across all 1 revision of this API.