API WORKFLOW
Hypit API tutorial: list models, generate video and collect output
A practical guide to the model catalogue, reference inputs, asynchronous video jobs, idempotency, polling, assets and errors.
Edited by HypitAI · Reviewed
Identify the hosted API route
Direct API generation differs from a local Agent, Run and Build. The API submits generation work; a complete remix still needs scripting, composition and acceptance.
List models available to the key
Use endpoints in the returned model card to determine video support. Keep the key in server-side environment variables.
curl https://hypit.ai/v1/models \
-H "Authorization: Bearer $HYPIT_API_KEY"Submit a minimal video job
HTTP 202 and a job id mean admission or queueing, not a completed clip.
curl https://hypit.ai/v1/videos \
-H "Authorization: Bearer $HYPIT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ranking-demo-v1" \
-d "{\"model\":\"bytedance/seedance-2\",\"prompt\":\"a presenter introduces a ranked list\",\"seconds\":5,\"resolution\":\"720p\",\"aspect_ratio\":\"9:16\"}"Use the intended reference slot
Reference images, frame slots, reference videos and video-to-video sources differ.
| Goal | Field | Check |
|---|---|---|
| Appearance | input_reference / reference_image_urls | Not a first frame |
| Opening/final frame | first_frame / last_frame | Model support |
| Motion/pacing | reference_videos | Reachable URL and length |
| Video-to-video | ref_video_url | Model support |
| Audio | reference_audios | Format and capability |
Poll, then collect assets
Query the original job to a terminal state, then request assets. Signed URLs expire and should be refreshed.
curl https://hypit.ai/v1/jobs/<job-id> -H "Authorization: Bearer $HYPIT_API_KEY"
curl https://hypit.ai/v1/jobs/<job-id>/assets -H "Authorization: Bearer $HYPIT_API_KEY"Keep the idempotency key on retry
A network failure can happen after admission. Find the original job first; keep the same key only for the same business request.
Diagnose by failure location
400 means invalid input; 404 model_not_found means no model routes for this key and endpoint; 429 requires Retry-After; queue_expired is terminal. Retain redacted request details, never credentials.