wylon
POSThttps://api.wylon.cn/v1/contents/generations/tasks
GEThttps://api.wylon.cn/v1/contents/generations/tasks/{task_id}
DELETEhttps://api.wylon.cn/v1/contents/generations/tasks/{task_id}

Asynchronous video generation

Use one asynchronous task API for text-to-video, first-frame, last-frame, and first-and-last-frame video-with-audio generation (FL2VA), plus multimodal reference video-with-audio generation (Ref2VA). Query the task by ID and download the MP4 result after it succeeds.

Authorization and request format

Authorizationstring · headerrequired
Bearer token. Create an API key in the Dashboard and store it in the $WYLON_API_KEY environment variable.
Content-Typestring · headerrequired
Must be application/json when creating a task.

Confirm model capabilities

FL2VA and Ref2VA use separate models. Call List models first to confirm that your API key can access the target model.

Model IDCapabilitySupported inputs
MiniMaxAI/MiniMax-H3Text-to-video and first-frame, last-frame, or first-and-last-frame video with audioText and 0–2 images
MiniMaxAI/MiniMax-H3-Ref2VAMultimodal reference video with audioText + at least one reference image or video; reference audio may also be added
ParameterFL2VARef2VADefault
duration5–15 seconds5–15 seconds5
resolution768P768P768P
ratio21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive21:9, 16:9, 4:3, 1:1, 3:4, 9:1616:9; adaptive when FL2VA includes images

Create a video task

Pass the prompt and reference media in the content array. Every request must contain exactly one non-empty type=text block. The following example creates an FL2VA task from a first-frame image.

Create task
curl -sS --max-time 60 \
  -X POST "https://api.wylon.cn/v1/contents/generations/tasks" \
  -H "Authorization: Bearer ${WYLON_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "type": "video",
    "model": "MiniMaxAI/MiniMax-H3",
    "content": [
      {"type": "text", "text": "Slowly push the camera forward as the subject turns naturally in the breeze, maintaining a cinematic look."},
      {"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}, "role": "first_frame"}
    ],
    "duration": 5,
    "resolution": "768p",
    "ratio": "16:9"
  }' -o video-create-response.json

Create parameters

typestringoptional
Use video for video generation. If omitted, the server treats the request as a video task.
modelstringrequired
The complete model ID provided by wylon, such as MiniMaxAI/MiniMax-H3 or MiniMaxAI/MiniMax-H3-Ref2VA. Check access in the Model Hub or through List models.
contentarrayrequired
Video-generation input blocks.
typestringrequired
One of text, image_url, video_url, or audio_url.
textstringrequired for text blocks
The generation prompt. Every request must contain exactly one non-empty text block.
image_url.urlstringrequired for image blocks
A public HTTPS image URL or data:image/<format>;base64,<data>.
video_url.urlstringrequired for video blocks
A public HTTPS video URL. Base64 is not supported.
audio_url.urlstringrequired for audio blocks
A public HTTPS audio URL or data:audio/<format>;base64,<data>.
rolestringrequired for media blocks
Images support first_frame, last_frame, or reference_image; videos support reference_video; audio supports reference_audio. A single first-frame image may omit role.
durationintegeroptional
Requested video duration in seconds. If omitted, the selected model's default applies. Supported values and defaults depend on the model.
resolutionstringoptional
Requested output resolution tier. If omitted, the selected model's default applies. Supported values and output dimensions depend on the model.
ratiostringoptional
Requested video aspect ratio. If omitted, the selected model's default applies. Supported values depend on the model.
negative_promptstringoptional
Describes content to exclude from the generated result. Support and behavior depend on the selected model.
seedintegeroptional
Controls generation randomness. Support, valid values, and reproducibility depend on the selected model.
safety_identifierstringoptional
A stable end-user identifier for safety tracing. Do not send direct identifiers such as names or email addresses.
execution_expires_afterintegeroptional
Task execution expiry threshold in seconds. The task may stop after this threshold is exceeded.

Input combinations and limits

Generation modecontent combination
Text-to-videotext
First-frame video with audiotext + one image_url with role=first_frame, or with role omitted
Last-frame video with audiotext + one image_url with role=last_frame
First-and-last-frame video with audiotext + two image_url blocks whose roles are first_frame and last_frame
Multimodal reference video with audiotext + at least one reference image or video block; reference audio may also be added
Match input roles to the generation mode
  • FL2VA: Do not mix first_frame / last_frame with Ref2VA reference_* roles. For two-image requests, label one first frame and one last frame.
  • Ref2VA: reference_audio cannot be the only media input. Include at least one reference_image or reference_video.

Ref2VA request example

{
  "type": "video",
  "model": "MiniMaxAI/MiniMax-H3-Ref2VA",
  "content": [
    {"type": "text", "text": "Use the reference character and camera motion, timed to the audio."},
    {"type": "image_url", "image_url": {"url": "https://example.com/character.jpg"}, "role": "reference_image"},
    {"type": "video_url", "video_url": {"url": "https://example.com/camera-motion.mp4"}, "role": "reference_video"},
    {"type": "audio_url", "audio_url": {"url": "https://example.com/music.mp3"}, "role": "reference_audio"}
  ],
  "duration": 8,
  "resolution": "768p",
  "ratio": "16:9"
}

Input media limits

TypeFormatsPer-file limitsCount / duration
ImageJPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF30 MB; 300–5760 px; aspect ratio 0.4–2.5Up to 2 for FL2VA or 9 for Ref2VA
VideoMP4 or MOV; H.264/AVC or H.265/HEVC; AAC or MP3 audio, plus PCM in MOV50 MB; 2–15 seconds; 300–5760 px; aspect ratio 0.4–2.5; 23.976–60 fpsUp to 3 for Ref2VA; 15 seconds total for MiniMax H3
AudioWAV, MP315 MB; 2–15 seconds eachUp to 3 for Ref2VA; 15 seconds total for MiniMax H3

Input images are measured by valid image count, while input video and audio are measured by valid duration. Output is measured by successfully generated duration and resolution. See the pricing page and your bill for current rates.

Query a task

Query the task using the id returned by the create response. Set detail=true to include the effective video_parameters in the response.

Query task
VIDEO_TASK_ID=$(jq -r '.id' video-create-response.json)

curl -sS --get \
  "https://api.wylon.cn/v1/contents/generations/tasks/${VIDEO_TASK_ID}" \
  -H "Authorization: Bearer ${WYLON_API_KEY}" \
  --data-urlencode "detail=true" \
  -o video-task-response.json
StatusMeaningRecommended action
queuedTask accepted and waiting to runQuery again later
runningVideo is being generatedQuery again later
succeededTask succeededRetrieve and download the video
failedTask failedRead error
cancelledQueued task was cancelledStop polling
expiredTask or result expiredCreate a new task if needed

Read and download the result

When status=succeeded and file_status=available, the video URL is available at content.video_url. A task returns only one MP4. If native audio is generated, it is embedded in the same file; no separate audio file or metadata is returned.

Successful result
{
  "id": "9065e7fd-2845-4e26-8850-1cf49a5d57c5",
  "status": "succeeded",
  "type": "video",
  "content": {
    "type": "video_url",
    "video_url": "https://example.com/generated/output.mp4?signature=REDACTED",
    "video_url_expires_at": 1788853117
  },
  "file_status": "available",
  "model": "MiniMaxAI/MiniMax-H3",
  "duration": 5,
  "resolution": "768p",
  "ratio": "16:9",
  "framespersecond": 24,
  "width": 1344,
  "height": 768,
  "output_format": "mp4",
  "watermark": true
}
Download result
VIDEO_URL=$(jq -r '.content.video_url // empty' video-task-response.json)
curl -L --fail --show-error "${VIDEO_URL}" -o generated-video.mp4

The signed URL includes short-lived access credentials, so downloading normally does not require the wylon API key. Do not log or disclose the full signed URL.

Cancel or delete a task (Coming soon)

cURL: cancel or delete
curl -sS -X DELETE \
  "https://api.wylon.cn/v1/contents/generations/tasks/${VIDEO_TASK_ID}" \
  -H "Authorization: Bearer ${WYLON_API_KEY}"

Deleting a task record or cancelling a task may be irreversible. Confirm the task ID and current status before proceeding.

Error handling and production guidance

Status codeCommon causeRecommended action
400Invalid prompt, media type, role, count, file specification, or model capabilityCorrect the request based on the error code and current model limits
401, 403Invalid key or insufficient model or task permissionsCheck authentication and account permissions
404Model or task not foundCheck the complete model ID, task ID, and environment
429Rate, concurrency, or capacity limit reachedReduce the request rate and retry later
500, 503Internal service error or model temporarily unavailableIf creation succeeded, query the original task before retrying
沪ICP备2026010432号-1沪公网安备31010402336632号