Video generation

REST contracts for Alibaba Video, HEYGEN AGENT, MARS, MOON, MiniMax, OMNI, SATURN, VECTOR, VENUS and X. 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. Check cost_status to see whether funds were reserved, charged or refunded.

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

HappyHorse 1.1 accepts 480P, 720P and 1080P. If an existing task returns lifecycle_conflict, keep its ID and contact support; do not create another task to retrieve the result.

HappyHorse 1.1 supports text-to-video, first-frame image-to-video and reference-to-video. 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. hh11_r2v maps to reference_to_video with model:"happyhorse-1.1-r2v", hh10_edit maps to video_edit with model:"happyhorse-1.0-video-edit", and kf2v maps to keyframe_to_video with model:"wan2.2-kf2v-flash" or model:"wan2.1-kf2v-plus". HappyHorse reference_to_video is the one HappyHorse operation that requires an explicit model: an omitted model is never routed to r2v.

REST accepts wan3.0-video-prime via model:"wan3.0-video-prime" for text_to_video/image_to_video/reference_to_video; it is rejected for video_edit/video_extend/file_to_video/link_to_video, which only base wan3.0-video implements. HappyHorse 1.1 accepts 480P/720P/1080P on text_to_video, image_to_video and reference_to_video; HappyHorse 1.0 edit accepts 720P/1080P. keyframe_to_video requires durationSeconds but ignores its value: the provider always returns exactly 5 seconds. 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. HappyHorse reference_to_video takes 1 to 9 such images in referenceImages, each with a shortest side of at least 400 px, and the prompt refers to them as [Image 1], [Image 2] and so on in list order. 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 returns data.url, data.storedFileId, data.mimeType and data.sizeBytes. For descriptors that also require measured geometry or duration, follow the media input guide.

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, hh11_r2v, wan_t2v, wan_i2v, wan_r2v, wan_edit, wan_extend, wan_file, wan_link, hh10_edit, kf2v

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. Use direct public HTTPS URLs or URLs returned by upload.

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 uses an operator-managed queue. Confirm access and expected processing time before using it in a time-sensitive workflow.

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 direct URL example is {source:"url",image_url:"https://media.example.com/product-front.png",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 lists capabilities and supported inputs.

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:"https://media.example.com/product-front.png"}; 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.

Save the status route for the selected variant together with its task ID. 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

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. Read the returned billing fields and your transaction history; a missing amount does not mean the request was free.

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. Confirm access to the chosen execution mode before submission; do not switch 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 returns data.url, data.storedFileId, data.mimeType and data.sizeBytes. Use data.url for URL fields. To obtain measured dimensions, duration or other descriptor metadata, send the returned storedFileId to the import route below. Save completed results before their retention expires.

Import a reference and build its descriptor

For fields such as Alibaba firstFrame, import the image to obtain an owned file ID and measured metadata. Send exactly one source: a direct public HTTPS url, or the storedFileId from a previous upload under the same account. kind selects image, video, audio or document. Image import accepts PNG/JPEG/WebP up to 30 MiB; video MP4/MOV/WebM up to 100 MiB; audio up to 50 MiB; documents PDF/TXT/MD up to 20 MiB. Export office documents as PDF first. The target generation operation may impose smaller limits or fewer formats.

This example imports an image, selects its descriptor fields with jq, and submits a first-frame video request. Replace the example URL with your direct image link. The generation step uses your balance; import does not create a generation task.

set -e
curl --fail-with-body -sS "$FRANKLAB_BASE_URL/franklab/jobs/import" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://media.example.com/product-front.png","kind":"image"}' \
  -o imported-image.json

jq -e '.data | {storedFileId,url,mimeType,width,height,sizeBytes} | select(.storedFileId and .url and .width and .height)' imported-image.json > first-frame.json
jq -n --slurpfile firstFrame first-frame.json \
  '{operation:"image_to_video",prompt:"The product slowly rotates on a table.",resolution:"720P",durationSeconds:3,firstFrame:$firstFrame[0]}' > video-request.json
curl --fail-with-body -sS "$FRANKLAB_BASE_URL/make/alibaba/videos" \
  -H "X-API-Key: $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @video-request.json

For a previously uploaded image, replace the import body with {"storedFileId":"ID_FROM_UPLOAD_RESPONSE","kind":"image"}Copy. Use the real data.storedFileId; do not send url in the same request.