Image inputs

Send an image in one request

The main API uses content[].image_url.url: use a public image URL or a complete Base64 data URL. The SDK reads and encodes local files and submits them with the prompt in one request.

Image-to-video example

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":"The person naturally turns toward the camera as a breeze moves their hair and the camera slowly pushes in."},
        {"type":"image_url","image_url":{"url":"https://YOUR_IMAGE_HOST/first-frame.jpg"},"role":"first_frame"}
    ],
    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}")

Choose Image to video, then select URL, Base64 or a local file.

Image requirements

Single-frame PNG, JPEG or WebP, up to 8 MiB in the original file. Each side must be 32–8192 pixels; total pixels must not exceed 16 × 1024². Public HTTP(S) image URLs must use port 80 or 443. One first frame is supported; H3 Pro 5-second requests can additionally include one last_frame.

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
}