Create a video task

Create an asynchronous video task. An accepted request returns a task ID; query it to retrieve the video URL.

Endpoint

POSThttps://fablun.com/api/v3/contents/generations/tasks

Request headers

Parameter	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Recommended. 1–128 characters: letters, digits and _.:- only. Reuse the original value when retrying the same request.

Request parameters

Parameter	Type	Required	Default	Description
`model`	string	Yes	—	h3-pro or h3-standard; the model must be enabled for your account.
`content`	object[]	Yes	—	1–8 items, including at least one text item; optionally one image_url first frame. Combined prompts are limited to 2000 characters.
`resolution`	string	No	480p	480p / 720p. Set explicitly and check the model's supported presets.
`duration`	integer	No	5	Seconds. H3 Pro supports 5, 10 or 12 seconds for 480p text-to-video and image-to-video, and 5 seconds for 720p. See Models and specifications for other models.
`seed`	integer	No	-1	Omit or use -1 for random. Otherwise use 0–2147483647; zero is valid. Retrieval returns the actual seed.
`ratio`	string	No	16:9	1:1, 3:4, 4:3, 16:9 or 9:16 for H3 Pro at 480p and 720p. Actual supply depends on verified nodes.
`generate_audio`	boolean	No	true	true keeps audio; false returns a muted video without re-encoding its images.
`watermark`	boolean	No	false	Currently fixed to false.
`service_tier`	string	No	default	Only default is supported; flex is unavailable.
`execution_expires_after`	integer	No	172800	Task lifetime including queueing, in seconds: 3600–259200, subject to the platform limit.
`priority`	integer	No	0	0–9. Priority is applied within account fairness and waiting-task protection; running inference is not preempted.
`callback_url`	string	No	—	Public HTTPS callback URL. Omit it to poll directly.
`safety_identifier`	string	No	—	Your end-user identifier, up to 64 characters.

return_last_frame, camera_fixed, draft accept only false. Unsupported capabilities and unknown fields return 422.

The content object

Type	Field	Description
text	`text`	Required prompt text. Multiple text items are joined with newlines.
image_url	`image_url.url`	Public image URL or a complete Base64 data URL.
image_url	`role`	`first_frame` or `last_frame`; last_frame requires first_frame and H3 Pro, 5 seconds.

JSON · Text and first frame

{
  "content": [
    {
      "type": "text",
      "text": "The camera slowly pushes in as the person smiles naturally."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_IMAGE_HOST/first-frame.jpg"
      },
      "role": "first_frame"
    }
  ]
}

Request example

ModelModeResolutionDurationAspect ratioSeed

Python · Create and poll automatically

import os, time, uuid
from volcenginesdkarkruntime import Ark

client = Ark(
    api_key=os.environ["ARK_API_KEY"],
    base_url="https://fablun.com/api/v3",
)

request_key = str(uuid.uuid4())  # Generate only for a new task; reuse the saved value for network retries.
print("Idempotency-Key:", request_key)
task = client.content_generation.tasks.create(
    model="h3-pro",
    content=[
        {"type":"text","text":"At dawn, a butterfly lands on a white daisy. Macro shot, soft natural light."}
    ],
    resolution="480p", duration=5, ratio="16:9",
    
    extra_headers={"Idempotency-Key": request_key},
)
print("task_id:", task.id)  # Save the ID; resume polling the same task after a network interruption.

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = client.content_generation.tasks.get(task_id=task.id)
    if result.status == "succeeded":
        print(result.content.video_url)
        break
    if result.status in ("failed", "expired", "cancelled"):
        raise RuntimeError(result.error or result.status)
    time.sleep(2)
else:
    raise TimeoutError(f"Polling timed out; continue querying the original task: {task.id}")

Response fields

HTTP 200 · application/json

{
  "id": "cgt-0123456789abcdef0123456789abcdef"
}

Field	Type	Description
`id`	string	Task ID. Save it for retrieval, cancellation and troubleshooting.

HTTP 200 means the request was accepted, not that generation is complete. The video URL is returned in content.video_url .

First and last frames

H3 Pro supports first and last frames for 5-second videos at 480p or 720p, with 1:1, 3:4, 4:3, 16:9 and 9:16 aspect ratios. Supply one image per role; last_frame requires first_frame. A pair is billed as one video, with the usual cancellation, moderation and callback flow. return_last_frame is a separate output option and remains unsupported.

{
  "model": "h3-pro",
  "content": [
    {
      "type": "text",
      "text": "A red ball rolls from left to right."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_IMAGE_HOST/first-frame.jpg"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_IMAGE_HOST/last-frame.jpg"
      },
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "duration": 5,
  "ratio": "16:9",
  "generate_audio": true
}

Optional video compression

compress: boolean, default false. true enables CPU compression during Beijing delivery. Resolution, frame rate and audio are preserved. No extra generation fee. The original is delivered if savings are below 5% or encoding fails; compression.applied and reason describe the outcome. Normal moderation, expiry and signed callbacks apply.

{
  "model": "h3-pro",
  "content": [
    {
      "type": "text",
      "text": "A cat walks through a garden."
    }
  ],
  "resolution": "720p",
  "compress": true
}