HiAPI
この記事はまだお使いの言語で提供されていません。原文を表示しています。
ブログ

Guide

OmniHuman 2.0 Developer Guide: Capabilities, Pricing, and API Integration

An image + audio approach to talking-avatar video on HiAPI

Nov 16, 2026 9 min read
Layered thin paper sheets in stepped depth, cream base with graphite edges and one terracotta sheet; cover art for the OmniHuman 2.0 developer guide.
このページの内容
Generated with OmniHuman 2.0 on HiAPI: a single portrait plus an audio track driving a lip-synced avatar presenter.

What OmniHuman 2.0 actually does

OmniHuman 2.0 is an image-plus-audio video generator. You supply one still image of a person or an illustrated character and one audio track, and the model returns a video in which the character's mouth moves in sync with that audio. There is no text-to-video path here and no way to generate a clip without a source image — both inputs are mandatory on every call.

On HiAPI the route is exposed as omnihuman-2.0 and advertises four capabilities that all describe the same underlying behavior from different angles:

  • image-to-video — a still image is the visual seed; there is no separate motion prompt that creates a scene from scratch.
  • audio-to-video — the audio track drives the timing of the output; the video is as long as the audio.
  • lip-sync — speech or singing is matched to the character's mouth, which is the core of the model's value.
  • avatar-video — the practical use case: a talking presenter, a narrated character, a localized spokesperson.

Because the output inherits the source image's framing, this is not a model for cutting between shots or building a multi-scene sequence. One call yields one continuous take of one character, driven by one audio file. If your product needs a talking head that says a specific thing for a specific number of seconds, this is a direct fit. If you need camera choreography across multiple angles or generative background changes, you are looking at the wrong tool.

The sections that follow walk through the two required inputs, what the optional prompt can and cannot do, how length and billing are tied to your audio file, and a recommended order of operations for integration.

The two required inputs: image and audio

Both image_url and audio_url are required strings. Neither has a default, and omitting either produces a rejected request rather than a degraded result.

image_url

The image defines who appears in the video and, importantly, the geometry of the output. It accepts jpeg, png, or webp up to 10MB. Two constraints are worth validating before you upload:

  • Aspect ratio must be between 0.4 and 2.5 (width ÷ height). That excludes extremely tall phone screenshots and ultra-wide banners.
  • Each side must be between 300 and 6000 px. A thumbnail smaller than 300 px on either axis is rejected; so is a 8K still.

The video keeps the image's aspect ratio and resolution. This is the single most under-appreciated fact about the route: your output dimensions are decided by the asset you send, not by a parameter. If your player expects 9:16, crop and resize the portrait to 9:16 before uploading rather than hoping the model reframes it.

audio_url

The audio drives both the mouth movement and the duration. It accepts mp3 or wav up to 15MB, with a duration between 4 and 300 seconds. Anything shorter than 4 seconds is rejected; anything longer than 300 seconds is rejected. The 15MB cap is a second, independent ceiling — a long, high-bitrate file can hit the size limit before the duration limit.

Because the video is exactly as long as the audio, the audio file is effectively your duration parameter. There is no duration field to override. Normalize your audio to a known length before submission and you will know both the runtime and the cost of the request in advance.

Using the prompt to direct expression and camera

prompt is optional, a string, and capped at 300 characters. It is a direction channel, not a script.

What it can steer:

  • Expression — for example a smile, a nod, a more serious demeanor.
  • Gestures — small body or hand movement accompanying the speech.
  • Camera — a slow push-in or similar framing movement.
  • Scene cues — light hints about the surrounding feel of the shot.

What it should not be expected to do:

  • Change identity. The character comes from the image. Asking the prompt for a different person will not work.
  • Alter speech content. The words are in the audio. The prompt does not rewrite or insert dialogue.
  • Override geometry. Aspect ratio and resolution still come from the image.

Practical guidance: keep prompts short, physical, and observable. "Smiling while nodding, slow push-in" is a good shape — it names a facial expression, a gesture, and a camera move in one sentence. Vague mood adjectives tend to produce less predictable results than concrete motion cues. And because the cap is 300 characters, there is no reason to pad; a rejected or truncated prompt is pure friction.

How length and cost are determined

Two things are decided by your audio file, and it is worth stating them together because they are really one fact.

Duration. The output video is as long as the audio track, within the 4–300 second window. There is no separate duration parameter.

Billing. OmniHuman 2.0 bills per second of output, and the price factor is estimated_seconds. The official per-second rate is $0.10 per second, and is also listed on the HiAPI pricing panel for this route; the important engineering point is the shape of the cost curve, not the number. Cost scales linearly with audio length, and the value you pass as estimated_seconds is what the estimate is computed from.

That gives you a clean planning formula: cost ≈ audio duration in seconds × the per-second rate. A 30-second narration is thirty billing units; a 300-second one is ten times that. Before you generate anything, compute the duration of the audio file you are about to submit and set estimated_seconds to that value. Two failure modes follow from getting this wrong:

  • Underestimating means your estimate does not match the work actually performed.
  • Skipping the estimate means you are submitting a request whose cost you have not computed, which is hard to defend in a batch pipeline.

If you are building a user-facing product, surface the duration to the user before generation — "this will produce a 47-second video" is a far better confirmation prompt than a spinner. And enforce your own length cap at the audio-upload layer, because that is where the cost is actually incurred.

Integration flow and pre-flight checks

The order of operations matters more than the code. Validate cheap things first so expensive failures never happen.

1. Validate and normalize the image

Check the MIME type is jpeg, png, or webp, and the file is under 10MB. Decode the dimensions and confirm the aspect ratio lands in 0.4–2.5 and each side is 300–6000 px. If the asset is off-spec, crop or resize it now — this is also where you set the final output geometry, since the video inherits the image's aspect ratio and resolution.

2. Validate the audio

Confirm the format is mp3 or wav and the file is under 15MB. Read the duration and check it sits between 4 and 300 seconds. Do this from the file's own metadata rather than trusting whatever your upload widget reported.

3. Set estimated_seconds

Take the audio duration you just measured and pass it as estimated_seconds. This is the price factor, so it should be derived from the file, not from a user-supplied guess.

4. Compose and submit

Build the request with image_url, audio_url, an optional prompt under 300 characters, and estimated_seconds. Submit it through the HiAPI unified interface and treat the returned video as one continuous take.

5. Handle the failure branches

Each check above has a rejection path: oversize or wrong-format image, out-of-range ratio or pixel dimensions, audio under 4 seconds, audio over 300 seconds or over 15MB, prompt over 300 characters, missing required field. Catch these client-side and return an actionable message rather than letting the API reject a request you already paid attention to. The full parameter set lives on the OmniHuman 2.0 model page.

Parameter reference and common pitfalls

A condensed view of the route's request schema.

Parameters

  • image_url — required, string. Character image: real person or illustration. jpeg / png / webp, ≤10MB, ratio 0.4–2.5, each side 300–6000 px. Sets output aspect ratio and resolution.
  • audio_url — required, string. Speech or singing that drives lip-sync. mp3 / wav, ≤15MB, 4–300 seconds. Sets output length.
  • prompt — optional, string, max 300 characters. Direction for scene, expression, gestures, and camera.
  • estimated_seconds — the billing factor; derive it from audio duration.

Pitfalls

  • Assuming a duration parameter exists. There is none. Trim the audio if you want a shorter video.
  • Expecting a fixed output size. The video inherits the image's ratio and resolution, so a square portrait gives a square video.
  • Uploading a portrait that is too tall or too wide. Ratios outside 0.4–2.5 are rejected; check before upload, not after.
  • Crossing two audio limits. Duration and file size are independent caps; a compliant duration with a bloated file still fails.
  • Under-4-second audio. Very short clips are rejected, which trips up demo pipelines that use placeholder tones.
  • Overloading the prompt. It steers delivery and camera, not identity or dialogue. Past 300 characters it is simply invalid.
  • Hardcoding a price into your product. Rates live on the pricing panel; compute cost from seconds at request time so a panel update does not desynchronize your UI.

When to choose OmniHuman 2.0

Choose it when the job is "make this character say this audio." That covers narrated explainers with a fixed presenter, localized spokesperson videos where you swap the audio track per language, illustrated avatars reading scripted lines, and any pipeline where the source portrait is already produced and only the delivery needs to be generated.

The fit is strong when your requirements are: one character, one continuous take, deterministic length, and a known cost computable from audio duration before you spend anything. The per-second billing and the audio-driven duration make budgeting unusually simple — you can price a batch job from a folder of audio files alone.

Look elsewhere when you need text-to-video with no source image, multi-scene editing, camera moves the prompt cannot express, or outputs whose resolution differs from the input asset. And if your audio is routinely shorter than a few seconds, plan for a different approach entirely, since the route's floor is above that.

If the constraints above match your project, start from the model page and validate your assets against the checks in this guide before your first real call.

永続的なAIアーティファクトで開発を始める

APIキーを取得して、タスクベースの1つのAPIで画像・動画・音声モデルを呼び出せます。

APIドキュメントを読む