Skip to main content
POST
/
api
/
public
/
v1
/
asset
/
start
curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "veo-3.1",
    "prompt": "A cinematic shot of a fox running through autumn leaves at sunrise.",
    "aspect_ratio": "9:16",
    "duration": 8,
    "resolution": "720p"
  }'

{
  "asset_ids": ["662f8c1d3a4b5e6f70123456"],
  "status": "generating",
  "count": 1,
  "cost_per_generation": 60,
  "total_cost": 60
}

​
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

​
type
string
required
image or video. Must match the type of the model you select.
​
model
string
required
The model identifier. See List Models for available identifiers and capabilities.
​
prompt
string
required
Text prompt describing the asset to generate. Some models cap the prompt length — check the model page.
​
references
array
Reference media for the model. Required for image-to-video, motion control, edit, and reference-based models.Not used for models with named input slots (e.g. kling-motion-control, veo-3.1-flf). See Named input slots below.Each item must have exactly one of:
​
generation_count
number
default:"1"
Number of variations to generate from the same prompt. Must be between 1 and 4. Credits are debited per generation.
​
aspect_ratio
string
One of the model’s supported aspect ratios. Defaults to the model’s default if omitted.
​
resolution
string
One of the model’s supported resolutions. Defaults to the model’s default if omitted.
​
duration
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.
​
model_settings
object
Per-model toggles such as generateAudio, camera_fixed, quality. See the model page for available keys.
​
parent_media_id
string
ID of an existing media in the space. Used to inherit reference avatars or to group variations under a parent.
​
avatar_description
string
For Seedance 2.0 UGC only — appearance and actions of the subject (separate from the script).
​
webhook_url
string
URL that will receive a notification when generation completes (success or failure).

​
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. end_image requires start_image). Models with named slots:
ModelNamed slots
kling-prostart_image (optional) + end_image (optional)
kling-motion-control, kling-motion-control-pro, kling-v3-motion-pro, kling-v3-motion-standardstart_image + motion_video
kling-o3-edit-pro, kling-o3-edit-standardsource_video
veo-3.1-flffirst_frame + last_frame
veo-3.1-extend, grok-imagine-video-edit, bytedance-upscalersource_video

​
Response

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

​
Examples

curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "veo-3.1",
    "prompt": "A cinematic shot of a fox running through autumn leaves at sunrise.",
    "aspect_ratio": "9:16",
    "duration": 8,
    "resolution": "720p"
  }'

{
  "asset_ids": ["662f8c1d3a4b5e6f70123456"],
  "status": "generating",
  "count": 1,
  "cost_per_generation": 60,
  "total_cost": 60
}

​
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.
  • Use Get Pricing for a dry-run cost estimate before submitting.