Submit Asset Generation

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"
  }'

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": "image",
    "model": "flux-2-pro",
    "prompt": "Product shot of a ceramic mug on a marble counter.",
    "aspect_ratio": "1:1",
    "folder_id": "662f8c1d3a4b5e6f70123456"
  }'

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": "grok-imagine-video",
    "prompt": "The subject walks forward confidently.",
    "references": [
      { "url": "https://example.com/subject.jpg" }
    ],
    "duration": 6,
    "resolution": "720p"
  }'

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": "grok-imagine-video",
    "prompt": "The subject walks forward confidently.",
    "references": [
      { "asset_id": "662f8c1d3a4b5e6f70123456" }
    ],
    "duration": 6
  }'

# Derive a video from an existing image asset. The asset is passed BOTH as the
# model reference AND as parent_media_id, so the dashboard links them in the
# history tree (and the video inherits the image's folder).
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": "grok-imagine-video",
    "prompt": "The subject turns slowly toward the camera.",
    "references": [
      { "asset_id": "662f8c1d3a4b5e6f70123456" }
    ],
    "parent_media_id": "662f8c1d3a4b5e6f70123456"
  }'

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": "kling-v3-pro",
    "prompt": "The character smiles and waves at the camera.",
    "references": [
      { "avatar_id": "6630000000000000deadbeef" }
    ]
  }'

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": "kling-v3-motion-pro",
    "prompt": "Apply the motion to the subject naturally.",
    "start_image": { "url": "https://example.com/subject.jpg" },
    "motion_video": { "asset_id": "662f8c1d3a4b5e6f70123456" }
  }'

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-flf",
    "prompt": "A smooth transition between the two frames.",
    "first_frame": { "url": "https://example.com/frame-start.jpg" },
    "last_frame": { "url": "https://example.com/frame-end.jpg" },
    "aspect_ratio": "16:9",
    "duration": 8
  }'

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": "kling-o3-edit-pro",
    "prompt": "Change the background to a tropical beach.",
    "source_video": { "asset_id": "662f8c1d3a4b5e6f70123456" }
  }'

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

{
  "error": "Validation failed",
  "details": [
    { "code": "missing_field", "message": "prompt is required", "field": "prompt" }
  ]
}

{
  "error": "Insufficient credits. Required: 60, Available: 12",
  "details": [
    { "code": "not_eligible", "message": "Insufficient credits. Required: 60, Available: 12" }
  ]
}

{
  "error": "This model requires one of the following plans: PRO, ENTREPRISE.",
  "details": [
    { "code": "not_eligible", "message": "This model requires one of the following plans: PRO, ENTREPRISE." }
  ]
}

POST

api

public

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"
  }'

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": "image",
    "model": "flux-2-pro",
    "prompt": "Product shot of a ceramic mug on a marble counter.",
    "aspect_ratio": "1:1",
    "folder_id": "662f8c1d3a4b5e6f70123456"
  }'

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": "grok-imagine-video",
    "prompt": "The subject walks forward confidently.",
    "references": [
      { "url": "https://example.com/subject.jpg" }
    ],
    "duration": 6,
    "resolution": "720p"
  }'

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": "grok-imagine-video",
    "prompt": "The subject walks forward confidently.",
    "references": [
      { "asset_id": "662f8c1d3a4b5e6f70123456" }
    ],
    "duration": 6
  }'

# Derive a video from an existing image asset. The asset is passed BOTH as the
# model reference AND as parent_media_id, so the dashboard links them in the
# history tree (and the video inherits the image's folder).
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": "grok-imagine-video",
    "prompt": "The subject turns slowly toward the camera.",
    "references": [
      { "asset_id": "662f8c1d3a4b5e6f70123456" }
    ],
    "parent_media_id": "662f8c1d3a4b5e6f70123456"
  }'

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": "kling-v3-pro",
    "prompt": "The character smiles and waves at the camera.",
    "references": [
      { "avatar_id": "6630000000000000deadbeef" }
    ]
  }'

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": "kling-v3-motion-pro",
    "prompt": "Apply the motion to the subject naturally.",
    "start_image": { "url": "https://example.com/subject.jpg" },
    "motion_video": { "asset_id": "662f8c1d3a4b5e6f70123456" }
  }'

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-flf",
    "prompt": "A smooth transition between the two frames.",
    "first_frame": { "url": "https://example.com/frame-start.jpg" },
    "last_frame": { "url": "https://example.com/frame-end.jpg" },
    "aspect_ratio": "16:9",
    "duration": 8
  }'

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": "kling-o3-edit-pro",
    "prompt": "Change the background to a tropical beach.",
    "source_video": { "asset_id": "662f8c1d3a4b5e6f70123456" }
  }'

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

{
  "error": "Validation failed",
  "details": [
    { "code": "missing_field", "message": "prompt is required", "field": "prompt" }
  ]
}

{
  "error": "Insufficient credits. Required: 60, Available: 12",
  "details": [
    { "code": "not_eligible", "message": "Insufficient credits. Required: 60, Available: 12" }
  ]
}

{
  "error": "This model requires one of the following plans: PRO, ENTREPRISE.",
  "details": [
    { "code": "not_eligible", "message": "This model requires one of the following plans: PRO, ENTREPRISE." }
  ]
}

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:

Show item properties

url

string

Direct publicly accessible URL of the reference media file. Supported formats:

Images: .jpg / .jpeg / .png / .webp
Videos: .mp4 / .mov / .webm / .m4v

asset_id

string

ID of an existing asset in your Hoox space media library (as returned by /asset/start or /asset/status). The server resolves the URL automatically — no need to re-upload.

avatar_id

string

ID of an avatar defined in your Hoox space. The avatar’s thumbnail image is used as the reference.

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 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.

folder_id

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.

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).

file_name

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. end_image requires start_image). Models with named slots:

Model	Named slots
`kling-pro`	`start_image` (optional) + `end_image` (optional)
`kling-motion-control`, `kling-motion-control-pro`, `kling-v3-motion-pro`, `kling-v3-motion-standard`	`start_image` + `motion_video`
`kling-o3-edit-pro`, `kling-o3-edit-standard`	`source_video`
`veo-3.1-flf`	`first_frame` + `last_frame`
`veo-3.1-extend`, `grok-imagine-video-edit`, `bytedance-upscaler`	`source_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"
  }'

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": "image",
    "model": "flux-2-pro",
    "prompt": "Product shot of a ceramic mug on a marble counter.",
    "aspect_ratio": "1:1",
    "folder_id": "662f8c1d3a4b5e6f70123456"
  }'

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": "grok-imagine-video",
    "prompt": "The subject walks forward confidently.",
    "references": [
      { "url": "https://example.com/subject.jpg" }
    ],
    "duration": 6,
    "resolution": "720p"
  }'

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": "grok-imagine-video",
    "prompt": "The subject walks forward confidently.",
    "references": [
      { "asset_id": "662f8c1d3a4b5e6f70123456" }
    ],
    "duration": 6
  }'

# Derive a video from an existing image asset. The asset is passed BOTH as the
# model reference AND as parent_media_id, so the dashboard links them in the
# history tree (and the video inherits the image's folder).
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": "grok-imagine-video",
    "prompt": "The subject turns slowly toward the camera.",
    "references": [
      { "asset_id": "662f8c1d3a4b5e6f70123456" }
    ],
    "parent_media_id": "662f8c1d3a4b5e6f70123456"
  }'

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": "kling-v3-pro",
    "prompt": "The character smiles and waves at the camera.",
    "references": [
      { "avatar_id": "6630000000000000deadbeef" }
    ]
  }'

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": "kling-v3-motion-pro",
    "prompt": "Apply the motion to the subject naturally.",
    "start_image": { "url": "https://example.com/subject.jpg" },
    "motion_video": { "asset_id": "662f8c1d3a4b5e6f70123456" }
  }'

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-flf",
    "prompt": "A smooth transition between the two frames.",
    "first_frame": { "url": "https://example.com/frame-start.jpg" },
    "last_frame": { "url": "https://example.com/frame-end.jpg" },
    "aspect_ratio": "16:9",
    "duration": 8
  }'

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": "kling-o3-edit-pro",
    "prompt": "Change the background to a tropical beach.",
    "source_video": { "asset_id": "662f8c1d3a4b5e6f70123456" }
  }'

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

{
  "error": "Validation failed",
  "details": [
    { "code": "missing_field", "message": "prompt is required", "field": "prompt" }
  ]
}

{
  "error": "Insufficient credits. Required: 60, Available: 12",
  "details": [
    { "code": "not_eligible", "message": "Insufficient credits. Required: 60, Available: 12" }
  ]
}

{
  "error": "This model requires one of the following plans: PRO, ENTREPRISE.",
  "details": [
    { "code": "not_eligible", "message": "This model requires one of the following plans: PRO, ENTREPRISE." }
  ]
}

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.
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.

List Voices Check Asset Status

Script

Generation

Export

Avatar

Voices

Assets

Folder

Overview

Authentication

Request Body

Named input slots

Response

Examples

Notes

​Overview

​Authentication

​Request Body

​Named input slots

​Response

​Examples

​Notes

Overview

Authentication

Request Body

Named input slots

Response

Examples

Notes