---
title: "Generate an image or a video"
method: POST
path: "/v1/grounded-generation"
---

# Generate an image or a video

`POST /v1/grounded-generation`

## Request

- Base URL: `https://api.octen.ai`
- URL: `https://api.octen.ai/v1/grounded-generation`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Generates an image or a video from a text prompt, grounded in reference material found by search.

## Request body

- GroundedGenerationRequest: Request body for the Grounded Generation API.
  - `modality` 'image' | 'video', required: The type of output to generate.
  - `prompt` string, required: The text description of what to generate.
  - `model` 'google/gemini-3-pro-image' | 'google/gemini-3.1-flash-image' | 'minimax/hailuo-3': The model to use. When omitted, the model default applies.
  - `aspect_ratio` '16:9' | '1:1' | '9:16': Aspect ratio of the output.
  - `duration` integer: Video length in seconds. Applies when `modality` is `video`. Values outside the allowed range are adjusted to the nearest bound.

## Response `200`

Successful grounded generation response. The task starts in `queued`.

- GroundedGenerationResponse
  - `request_id` string: Unique identifier for the request.
  - `generation_id` string, required: Unique task id, used to retrieve the result.
  - `modality` 'image' | 'video', required: The type of output this task generates.
  - `status` 'queued', required: Task state.
  - `created_at` integer, required: Unix timestamp in seconds when the task was created.

## Other responses

- `400`: Invalid params — Returned when a required parameter is missing or invalid.
- `401`: Invalid API Key — Returned when the API key is missing or invalid.
- `403`: Insufficient balance in account — Returned when the account balance is insufficient to complete the request.
- `429`: Exceeding the rate limit — Returned when the request exceeds the configured rate limit.
- `500`: Internal error — Returned when an unexpected server-side error occurs.

---

[API](https://skmtc.dev/octen/apis/octen-api.md) - [All operations](https://skmtc.dev/octen/apis/octen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octen/apis/octen-api/revisions/aaa6caaf46b0?raw)