Skip to main content
POST

​
Overview

Submits an asset (image or video) generation job and returns immediately with the IDs of the temporary assets being generated. Generations run in the background — poll /asset/status/{assetId} to track progress. Credits are debited up front based on the model and the parameters you send. Failed generations are automatically refunded.

​
Authentication

This endpoint requires API key authentication. Include your API key in the Authorization header.

​
Request Body

​
string
required
image or video. Must match the type of the model you select.
​
string
required
The model identifier. See List Models for available identifiers and capabilities.
​
string
required
Text prompt describing the asset to generate. Some models cap the prompt length — check the model page.
​
array
Reference media for the model. Required for image-to-video, motion control, edit, and reference-based models.Models with named input slots (e.g. kling-motion-control, veo-3.1-flf) expect dedicated top-level fields instead — see Named input slots below. They still accept a references array, mapped onto their slots in order, so you never have to migrate an existing call.Each item must have exactly one of:
​
array
Named characters or objects to inject in the generation, each described by several images of the same subject and referenced in the prompt as @name. Only for models that expose an element capability (kling-v3-pro, kling-v3-standard) — see Elements below.
​
number
default:"1"
Number of variations to generate from the same prompt. Must be between 1 and 4. Credits are debited per generation.
​
string
One of the model’s supported aspect ratios. Defaults to the model’s default if omitted.
​
string
One of the model’s supported resolutions. Defaults to the model’s default if omitted.
​
integer
Video duration in seconds (e.g. 8). Use one of the model’s supported durations — see the duration enum in the model’s input_schema from Get Model. The server converts it to the model’s expected format automatically.
​
object
Per-model toggles such as generateAudio, camera_fixed, quality. See the model page for available keys.
​
string
ID of the source asset this generation is derived from — an edit, animation (image-to-video), upscale, restyle, or variation. Set it whenever the output comes from an existing asset: it links the new asset to its source in the dashboard’s history tree so the full edit chain stays visible.This is separate from the model input: keep passing the source as a reference (asset_id / named slot like source_video) so the model receives it, and set parent_media_id to the same source id to record the lineage.When set, the generated assets also inherit the parent’s folder, and folder_id is ignored.
​
string
ID of an existing asset folder to place the generated asset(s) into. Create one with Create Folder (type: "assets") or list existing ones with List Folders. When working on a project or generating a batch, group its outputs in a dedicated folder so they stay organized and easy to find in the dashboard.
​
string
For Seedance 2.0 UGC only — appearance and actions of the subject (separate from the script).
​
string
URL that will receive a notification when generation completes (success or failure).
​
string
Predefined base file name for the produced asset, without extension (e.g. summer-campaign-hero). It is slugified server-side (lowercased, non-alphanumeric characters replaced by hyphens) and the correct extension is appended automatically. When omitted, a descriptive name is generated from the prompt.

​
Named input slots

Some models require specific media types in a fixed order — for example, a subject image and a motion reference video. For these models, instead of a generic references[] array, you pass named top-level properties that make the intent explicit. The named properties for a given model are listed on its model page and in the input_schema field returned by GET /models/{name}. Each named slot accepts the same object shape as a references[] item: exactly one of url, asset_id, or avatar_id. Slots are ordered — when a slot is optional, you may omit it, but you cannot provide a later slot while leaving an earlier one empty (e.g. last_frame requires first_frame). Models with named slots:
Passing a references array to one of these models is still supported: the items are mapped onto the slots above in order (first item → first slot, and so on). Named fields are clearer and are what the model pages document, but existing calls keep working.

​
Elements

Elements let you inject named characters or objects in a generation. Each element is described by several images of the same subject, and you refer to it in the prompt with @name — so a single prompt can direct several known subjects without ambiguity. Supported by kling-v3-pro and kling-v3-standard, up to 4 elements per request.
Rules
  • Each element needs at least 2 images of the same subject: the first is the frontal view, the others are additional angles (4 max).
  • The prompt must reference every element as @name. An unreferenced element is ignored by the model, so the request is rejected instead of burning credits.
  • name accepts letters, digits and underscores only (32 characters max), must be unique within the request, and cannot be refN or elementN — those are reserved for the internal rewriting of prompt references.
  • first_frame is required whenever you send elements.
  • Element images do not count toward the model’s references / named-slot limits.
Element names are yours: Hoox rewrites them into the positional placeholders the provider expects before submitting, so @sarah and @mug are what you write and what you read back in your own code.

​
Response

​
array
IDs of the created temporary assets. One ID per generation. Use these with /asset/status/{assetId}.
​
string
Always generating on success.
​
number
Number of generations launched.
​
number
Credits charged for one generation.
​
number
Total credits debited (cost_per_generation × count).

​
Examples

​
Notes

  • The endpoint returns as soon as the temp assets are created — the actual generation runs in the background and typically completes in 10–120 seconds depending on the model.
  • If you provide a webhook_url, it will be called when generation completes (success or failure).
  • Use List Models and Get Model to discover the parameters each model accepts, including named input slots and element support.
  • Use Get Pricing for a dry-run cost estimate before submitting.
  • When a generation is derived from an existing asset (edit, animation, upscale, restyle, variation), set parent_media_id to the source asset’s id so the dashboard keeps the full history chain. Pass the source as a reference for the model and as parent_media_id for the lineage.