Video generation

REST contracts for Alibaba Video, HEYGEN AGENT, MARS, MOON, MiniMax, OMNI, SATURN, VECTOR, VENUS and X. Contracts were checked against source on 8 September 2026; access and pricing depend on your account and the selected operation.

Connection and lifecycle

Base URL: https://apergrex.ru/franklab/api. Tables show full paths. Send your FrankLab key in X-API-Key, or Authorization: Bearer for HEYGEN. Never put keys in URLs. Make labels and selectors select a request branch; they are not necessarily REST fields.

export FRANKLAB_BASE_URL="https://apergrex.ru/franklab/api"
# FRANKLAB_KEY is supplied securely by your environment.

Check availability and a model-specific estimate before creation. Generation POST may reserve Franks; F is an internal accounting unit. Save the returned ID and poll the specified route. HTTP 200, queued/processing and an ID do not establish completion. Success requires a terminal state and output URL. For 400 inspect fields, 401/403 access, 404 route/ID, 409 conflicts and 429 rate limits; also check application code/success and the error body. After a timeout, reconcile existing work before another paid POST. A presumed refund is not verified settlement.

Required marks fields mandatory for the selected REST branch; conditional requirements are stated alongside them. Path and query inputs are identified explicitly. Do not send every field from a union schema in one request.

Modules

• FrankLab Alibaba Video
• FrankLab HEYGEN AGENT
• FrankLab MARS
• FrankLab MOON
• FrankLab MiniMax
• FrankLab OMNI
• FrankLab SATURN
• FrankLab VECTOR
• FrankLab VENUS
• FrankLab X

FrankLab Alibaba Video

Known limitation, 8 September 2026: the HappyHorse 1.1 480P check exposed a completion error, lifecycle_conflict. Submission is accepted, but the result and final settlement are unavailable. Avoid 480P until resolved. Keep an existing task ID and contact support; another POST creates a new task.

HappyHorse 1.1 supports text and first-frame generation. REST normally omits model; Make's happyhorse-1.1 label is not a REST model value. WAN uses model:"wan3.0-video". Make wan_t2v, wan_i2v, wan_r2v, wan_edit, wan_extend, wan_file, wan_link map respectively to the seven REST operation values in the table. hh10_edit maps to video_edit with model:"happyhorse-1.0-video-edit".

REST does not accept wan3.0-video-prime, even though Make lists it. HappyHorse 1.1 accepts 480P/720P/1080P; HappyHorse 1.0 edit accepts 720P/1080P. Before submission, check access to the selected operation, especially WAN edit/extend/file/link and HappyHorse edit.

Image descriptor: {storedFileId,url,mimeType,width,height,sizeBytes} from owned stored media. WAN video descriptor: {storedFileId,url,mimeType:"video/mp4",sizeBytes}. HappyHorse edit video additionally requires measured width,height,durationSeconds,fps and permits MP4/MOV. Document descriptor requires owned ID/URL, supported document MIME and size, optionally pageCount (at most 50). Do not invent IDs or measured metadata. /franklab/jobs/upload only returns a URL, so by itself it does not furnish a complete Alibaba descriptor. Obtain the required owned file IDs and metadata before submitting image or video input.

WAN reference requests use media:[{type:"reference_image",url:ownedURL}] (up to 10); the current REST DTO additionally supports referenceVideos and referenceAudios with measured metadata, while this Make communication does not send those arrays. These are distinct from referenceVideo, the clip to edit. Automatic WAN duration -1 reserves against a 30-second bound.

Routes and operations

REST parameters

happyhorse_text_to_video, happyhorse_image_to_video, wan_t2v, wan_i2v, wan_r2v, wan_edit, wan_extend, wan_file, wan_link, hh10_edit

poll_status

estimate

upload_source

Response and completion

Envelope code/msg/data. Submit data.taskId and status=queued; poll queued/processing/completed/failed/error. Completed video is data.videoUrl; final_cost_franks, refunded_cost_franks and cost_status describe settlement.

Minimal example

Replace OWNED_* placeholders with URLs of your own files. Check model access, the estimated cost and your available balance before submitting.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/make/alibaba/videos" \
  -H "X-API-Key: $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"operation":"text_to_video","prompt":"A blue paper cube rotates on a white background.","resolution":"720P","durationSeconds":3,"ratio":"16:9"}'

Estimate: POST /franklab/api/make/alibaba/estimate. For Alibaba add media=video and send only estimate-schema fields.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/make/alibaba/status/$TASK_ID" \
  -H "X-API-Key: $FRANKLAB_KEY"

FrankLab HEYGEN AGENT

Authentication uses the partner credential/session guard; REST examples use your FrankLab bearer API key. partner_heygen requires a previously saved credential belonging to the same partner. Keep account mode and credential ID consistent across submit, session polling, resources, videos and RPCs. The normal example uses the FrankLab account and never sends a provider secret.

Make avatarId, voiceId, styleId, brandKitId, callbackUrl, callbackId, incognitoMode map to REST snake-case fields shown below. filesJson becomes an actual JSON array in files. List pagination is limit plus token; responses may include hasMore and nextToken. Save an avatar look ID, not its group ID.

For generate_from_prompt, POST mode:"generate", GET the session until a video ID exists, then GET /v1/heygen/videos/{videoId} until a successful video URL exists. Failure/stopped/cancelled states are terminal; an empty URL is not success. A submit timeout or submission_unknown must be reconciled using existing session/task records before resubmitting. A session message can request further generation and is not a free metadata call. Stop is not a billing rollback. Provider-account and FrankLab-account billing paths differ; inspect the returned task/settlement evidence rather than assuming every session endpoint shares one tariff.

Routes and operations

REST parameters

generate_from_prompt, create_session

list_sessions

list_styles, getHeygenVideoAgentStyles, getHeygenBrandKits

get_session, list_videos, stop_session

get_resource

get_video

send_message

save_heygen_credential

getHeygenAgentAvatarLooks

getHeygenVoices

getHeygenVideoAgentSessions

Response and completion

Envelope success=true,data,meta. Session and video IDs are separate. Session may return data.sessionId/videoId/status/providerStatus; poll video endpoint for data.video and videoUrl/downloadUrl. Read failureCode/failureMessage; session existence is not finished output.

Minimal example

Replace OWNED_* placeholders with URLs of your own files. Check model access, the estimated cost and your available balance before submitting.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/heygen/video-agents" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"providerAccountMode":"franklab","prompt":"Create a short video of a blue paper cube rotating on a white background.","mode":"generate"}'

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/heygen/video-agents/$SESSION_ID" \
  -H "Authorization: Bearer $FRANKLAB_KEY"

FrankLab MARS

Text and image generation use model_name:"mars-v1-5", duration 3–15 seconds, mode:"std"|"pro"|"4k". The route chooses text/image intent; do not send Make mode:"text2video" as REST quality. Image generation requires image or image_list. Text generation rejects elements. Image generation allows at most three elements and rejects combining elements with voices. Multi-shot uses multi_shot, shot_type and multi_prompt:[{index,prompt,duration}].

Effects require the exact effect code and scene. For example effect_scene:"single_character",effect:"zoom_out",image:ownedURL; dual-character inputs also need image_tail. The machine contract retains every effect selector value. Trajectory transfer is the same motion-control API documented under VECTOR, with Make's legacy aliases translated as noted. Poll the matching route family, retain all task_result.videos, and inspect task_status_msg if the task fails.

Routes and operations

REST parameters

text2video, image2video

poll_status

effects

trajectory_transfer

getAllKusoks, getElementVoices

upload_source

Response and completion

Proxy envelope: code=0 (some routes accept 200), data.task_id. Poll data.task_status; successful task_result.videos[] contains url/id/duration. Read task_status_msg on failure. final_cost_franks is meaningful together with cost_status/cost_unit; reserved is not final settlement.

Minimal example

Replace OWNED_* placeholders with URLs of your own files. Check model access, the estimated cost and your available balance before submitting.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/videos/text2video" \
  -H "X-API-Key: $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"model_name":"mars-v1-5","prompt":"A blue paper cube rotates on a white background.","duration":3,"mode":"std","aspect_ratio":"16:9"}'

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/videos/text2video/$TASK_ID" \
  -H "X-API-Key: $FRANKLAB_KEY"

FrankLab MOON

moon_fast Make resolution choices are 480p/720p; moon_base adds 1080p/4k; moon_pro offers 480p/720p/1080p and mp4/mov. moon_mini is exposed for reference generation. Model-specific validators remain authoritative: a union enum does not make every combination valid.

Image input uses first_frame_image_url and optionally last_frame_image_url. References are arrays of URL strings, not objects and not Make field labels. Standard limits are 9 images, 3 videos, 3 audios; moon_pro extends reference arrays to 30 images, 10 videos and 10 audios with additional aggregate budgets. The legacy image_list first-frame slots remain capped at 9. Edit/extend need the source video URL; give a prompt for a deliberate edit. Uploaded owned media URLs are preferable; do not substitute customer assets in tests.

Estimate with the identical payload, then submit with a stable idempotency_key. Keep the returned ID and poll /make/moon/status/{taskId}. Check application code, phase, status, output URL and settlement together. An estimated or reserved final_cost_franks is a reserve amount; cost_status distinguishes it from confirmed cost.

Duration is an integer 4–15 for non-pro models. moon_pro allows -1 (automatic) or 4–30; for moon_pro video_edit omit duration or use -1. For moon_pro edit/extend and first/last-frame inputs, omit ratio or use adaptive.

Routes and operations

REST parameters

text_to_video, image_to_video, reference_to_video, video_edit, video_extend, estimate

poll_status

upload_source

Response and completion

Envelope code/msg/data. Submit data.taskId/task_id, status=queued, phase and idempotency metadata; status queued/processing/completed/failed. Result data.videoUrl (or normalized video URL in result), last_frame_url if requested. A failed task can have HTTP 200 with code=500. Reserved final_cost_franks is not final settlement.

Minimal example

Replace OWNED_* placeholders with URLs of your own files. Check model access, the estimated cost and your available balance before submitting.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/make/moon/videos" \
  -H "X-API-Key: $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"operation":"text_to_video","moonModel":"moon_fast","prompt":"A blue paper cube rotates on a white background.","duration":4,"resolution":"480p","ratio":"16:9","generate_audio":false}'

Estimate: POST /franklab/api/make/moon/estimate. Use the same body.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/make/moon/status/$TASK_ID" \
  -H "X-API-Key: $FRANKLAB_KEY"

FrankLab MiniMax

All five scenarios are supported by the stored-file REST schema. Text requires a concrete ratio (21:9,16:9,4:3,1:1,3:4,9:16) and no reference fields. Frame scenarios require the corresponding owned ID(s), ratio:"adaptive", and no reference arrays. Reference mode requires at least an image or video; audio alone is insufficient. Duplicate IDs across media arrays are rejected.

Upload URL JSON is {source_type:"url",kind:"image",url:"https://your-public-host.example/synthetic.png"}. For bytes use multipart source_type=make_file, kind=image, media_file=@synthetic.png; for a data URI use data_url_file=@source.dataurl with source_type=data_url. Upload transport caps one file at 64 MiB; per-media limits are smaller (image 30 MiB, video 50 MiB, audio 15 MiB). Reuse the returned stored_file_id.

The direct endpoint accepts one JSON file, not a JSON request body. Example file content for first frame: {version:"minimax_h3_direct_v1",idempotency_key:"video-docs-frame-001",scenario:"first_frame_to_video",prompt:"A paper cube rotates.",resolution:"768P",duration:4,first_frame:{source_type:"stored_file",stored_file_id:"OWNED_FILE_ID"}}. Make converts native file buffers to data URLs before building this file. Direct source kinds are stored_file/url/data_url; make_file is not a direct JSON source type.

Reuse the idempotency key for reconciliation of the same payload. A changed payload with the same key conflicts; repeat_token deliberately requests another generation and must not be added to evade a timeout. Respect 429 and retry timing; a failed polling request does not cancel provider work. No dedicated MiniMax estimate route was found in this controller.

Routes and operations

REST parameters

upload_media

create_video:text_to_video, create_video:first_frame_to_video, create_video:last_frame_to_video, create_video:first_last_frame_to_video, create_video:reference_to_video

create_video:direct

get_video_task

list_video_tasks

cancel_or_delete_video_task:cancel

cancel_or_delete_video_task:delete

Response and completion

Envelope code=200,msg=OK,data. task_id; queued/running/succeeded/failed/cancelled; succeeded video/video_url and owned stored_file_id; reserved_cost_franks, final_cost_franks, cost_status, usage, error. Lists data.items/page_num/page_size/total.

Minimal example

Replace OWNED_* placeholders with URLs of your own files. Check model access, the estimated cost and your available balance before submitting.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/make/minimax/videos" \
  -H "X-API-Key: $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"idempotency_key":"video-docs-synthetic-001","scenario":"text_to_video","prompt":"A blue paper cube rotates on a white background.","resolution":"768P","duration":4,"ratio":"16:9"}'

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/make/minimax/videos/$TASK_ID" \
  -H "X-API-Key: $FRANKLAB_KEY"

FrankLab OMNI

Google subscription mode is serviced by a separate operator. The 8 September 2026 check remained in the manual processing queue; automatic completion and an ETA are not established. This limitation concerns subscription mode, not all OMNI models.

The public OMNI module is separate from SATURN's legacy /v1/videos/omni-video alias. Use /make/omni/videos. Make model=omni selects omni_version; model=veo selects veo_version; the REST model is the resulting concrete value. poll_status is a GET operation, not a submit value.

For image-to-video supply one image source; for reference-to-video supply structured image references. A reference example is {source:"url",image_url:ownedURL,label:"cube"}. Use the same partner's returned interaction_id for edit/extend; never a provider-secret identifier. Extend is limited to omni_1_1; omni 1.0 rejects it. Veo uses 4/6/8 seconds, its own resolution and negative prompt; those options do not confer support on the Omni engine. GET /make/omni provides capability information but does not prove a completed generation.

google_flow_sub calls the separate Google subscription route with execution_mode:"google_subscription" and reference URL strings. Its polling envelope differs. Upload returns URL only; file-ID inputs require a real stored-file record. No dedicated estimate route exists in the Make OMNI controller.

Routes and operations

REST parameters

text_to_video, image_to_video, reference_to_video, edit, extend, veo3, veo3_fast

poll_status

google_flow_sub

upload_source

Response and completion

Make OMNI code/msg/data: taskId/task_id, status, videoUrl, interaction_id and billing fields. Poll completed/failed/processing; retain the interaction handle for edit/extend. google-sub uses proxy task_status/task_result.videos instead.

Minimal example

Replace OWNED_* placeholders with URLs of your own files. Check model access, the estimated cost and your available balance before submitting.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/make/omni/videos" \
  -H "X-API-Key: $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"model":"omni_1_1","operation":"text_to_video","prompt":"A blue paper cube rotates on a white background.","aspect_ratio":"16:9"}'

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/make/omni/status/$TASK_ID" \
  -H "X-API-Key: $FRANKLAB_KEY"

FrankLab SATURN

Select model_name:"saturn-v1" or "saturn-v1-5"; do not send Make's version selector in REST. Standard SATURN supports text, images, reference video, elements, voices and multi-shot controls with model-specific constraints. A reference item is {image_url:ownedURL}; each item must carry exactly one source. Native/base64 image inputs are limited to 10 MiB each. Video reference entries use video_url, optionally refer_type and keep_original_sound. Voice list supports up to two IDs.

Turbo has two explicit routes and model saturn-v1-5-turbo; standard reference/multi-shot/audio/quality controls are not interchangeable. Image Turbo derives framing from the image; text Turbo can set aspect_ratio. Extension reuses an existing video_id or owner-scoped source_task_id; no new source ID can be invented. Multi-image generation has its own route and status route.

AI preset list/generate are visible in Make and implemented as service methods, but the matching controller routes are absent in this source snapshot. They remain documented as BLOCKED. Preserve each variant's status route when polling; an old task ID must not cause another submit. Legacy /videos/omni-video aliases belong to SATURN, not Gemini OMNI.

Routes and operations

REST parameters

v1, v1-5

v1-5-turbo:text, v1-5-turbo:image

video_extend

multi_image2video

ai_presets:list

ai_presets:generate

poll_status

getAllKusoks, getElementVoices

upload_source

Response and completion

Proxy envelope: code=0 (some routes accept 200), data.task_id. Poll data.task_status; successful task_result.videos[] contains url/id/duration. Read task_status_msg on failure. final_cost_franks is meaningful together with cost_status/cost_unit; reserved is not final settlement.

Minimal example

Replace OWNED_* placeholders with URLs of your own files. Check model access, the estimated cost and your available balance before submitting.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/videos/saturn" \
  -H "X-API-Key: $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"model_name":"saturn-v1","prompt":"A blue paper cube rotates on a white background.","duration":3,"mode":"std","aspect_ratio":"16:9"}'

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/videos/saturn/$TASK_ID" \
  -H "X-API-Key: $FRANKLAB_KEY"

FrankLab VECTOR

VECTOR transfers motion from a reference video to an anchor image. Provide an image and public video URL; Make describes a 3–30-second reference clip. character_orientation:"image"|"video" selects the orientation source, keep_original_sound:"yes"|"no" controls reference audio. Profiles are auto, studio, cinema (REST also accepts compatibility aliases vector-v1/vector-v1-5). Quality is std/pro.

For an image use URL, base64/data URI, or image_file_data plus image_file_name for native bytes. JPG/PNG/WebP, up to 10 MiB in the Make input contract. Optional elements are {element_id} objects. list_tasks is GET with query parameters and no creation body. The Make action/task selectors are not REST request fields. Generation requires a reference video and an anchor image; listing tasks only reads their metadata.

Routes and operations

REST parameters

create

list_tasks

poll_status

upload_source

Response and completion

Proxy envelope: code=0 (some routes accept 200), data.task_id. Poll data.task_status; successful task_result.videos[] contains url/id/duration. Read task_status_msg on failure. final_cost_franks is meaningful together with cost_status/cost_unit; reserved is not final settlement.

Minimal example

Replace OWNED_* placeholders with URLs of your own files. Check model access, the estimated cost and your available balance before submitting.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/videos/motion-control" \
  -H "X-API-Key: $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"generation_profile":"studio","mode":"std","image":"OWNED_SYNTHETIC_IMAGE_URL","video":"OWNED_SYNTHETIC_MOTION_VIDEO_URL","character_orientation":"image","keep_original_sound":"no","duration":"3"}'

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/videos/motion-control/$TASK_ID" \
  -H "X-API-Key: $FRANKLAB_KEY"

FrankLab VENUS

Provide an anchor image and either sound_file (URL/base64/native file) or an existing audio_id. Make documents MP3/WAV/M4A/AAC audio files up to 5 MiB and 2–60 seconds; audio IDs may represent 2–300 seconds and must be recent (30 days). Native fields are image_file_data/image_file_name and sound_file_data/sound_file_name. Do not send both audio alternatives.

Make creates /v1/videos/avatar/image2video then polls /v1/tasks/{taskId}. Success requires a video in task_result.videos. The service has both tracked and legacy proxy paths selected by a runtime flag; missing cost fields must not be reported as zero cost or a verified refund. Verify actual billing evidence separately.

Routes and operations

REST parameters

create_avatar_video

poll_status

avatar_status

upload_source

Response and completion

Proxy envelope: code=0 (some routes accept 200), data.task_id. Poll data.task_status; successful task_result.videos[] contains url/id/duration. Read task_status_msg on failure. final_cost_franks is meaningful together with cost_status/cost_unit; reserved is not final settlement.

Minimal example

Replace OWNED_* placeholders with URLs of your own files. Check model access, the estimated cost and your available balance before submitting.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/videos/avatar/image2video" \
  -H "X-API-Key: $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"image":"OWNED_SYNTHETIC_AVATAR_URL","sound_file":"OWNED_SYNTHETIC_AUDIO_URL","mode":"std"}'

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $FRANKLAB_KEY"

FrankLab X

Use operation:"generation" with text only, image_url, or reference_images:[{url:ownedURL}]. Image and reference arrays are mutually exclusive. Make's source_mode is a UI selector and is not sent to REST. For edit or extension, provide video_url, omit image/reference inputs; extension may omit prompt. Duration is 1–15 seconds for generation/edit and 2–10 for extension; Make exposes a smaller set of convenient choices.

Without an explicit recognized model, single-image generation selects the latest image-to-video model; text and references use the compatible model. 1080p is restricted to latest single-image generation. execution_mode:"supergrok" supports generation from text/images/references only, requires publicly accessible HTTPS image URLs and separate partner admission; no edit/extend/video input. Its supported output limits can differ from the direct xai_api route. Do not infer entitlement from source options or switch execution modes automatically after a failure.

POST returns a FrankLab task ID; GET the same X route until terminal status and a usable URL. Keep cost_status with final_cost_franks. There is no dedicated estimate route in this controller; check your account’s pricing before creating a task.

Routes and operations

REST parameters

generation:text_to_video, generation:image_to_video, generation:reference_to_video, edit, extension

poll_status

upload_source

Response and completion

Proxy envelope: code=0 (some routes accept 200), data.task_id. Poll data.task_status; successful task_result.videos[] contains url/id/duration. Read task_status_msg on failure. final_cost_franks is meaningful together with cost_status/cost_unit; reserved is not final settlement.

Minimal example

Replace OWNED_* placeholders with URLs of your own files. Check model access, the estimated cost and your available balance before submitting.

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/videos/xai" \
  -H "X-API-Key: $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"operation":"generation","execution_mode":"xai_api","prompt":"A blue paper cube rotates on a white background.","duration":1,"resolution":"480p","aspect_ratio":"16:9"}'

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/v1/videos/xai/$TASK_ID" \
  -H "X-API-Key: $FRANKLAB_KEY"

Uploads and result retention

curl --fail-with-body -sS "$FRANKLAB_BASE_URL/franklab/jobs/upload" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -F "file=@synthetic.png;type=image/png"

Upload response: {"success":true,"data":{"url":"..."}}Copy. Use the actual returned URL. This response has no storedFileId, dimensions, fps or duration. ID/descriptor inputs require a separately verified owned file record. Retrieve completed results before their retention expires; do not publish signed URLs in logs or reports.