Video Generation API Reference

    FieldValue
    Base URLhttps://api.gate.ai
    AuthAuthorization: Bearer <API_KEY>

    Submit Video Task

    POST/api/v1/videos

    Submit an async video generation job. Returns 202 Accepted with job_id for polling. Pass Idempotency-Key for safe retries.

    Request Parameters

    NameInTypeRequiredDescription
    AuthorizationheaderstringYesGate.AI API Key. Format: Bearer <API_KEY>
    Content-TypeheaderstringYesRequest body format
    Idempotency-KeyheaderstringNoIdempotency key for safe retries — same key returns the existing job

    Request Body

    NameTypeRequiredDescription
    modelstringYesModel ID
    promptstringYesVideo prompt; describe subject, motion, scene, camera, and style. Limits vary by model: Sora 500 characters, Hailuo 2000 characters, Wan T2V 1500 characters, and Wan I2V 800 characters. Gate.AI does not enforce a hard limit; over-limit prompts are rejected upstream and surfaced as 502 / 503.
    durationintegerNoDuration in seconds; the allowed range varies by model
    resolutionstringNoOutput resolution: 480p, 720p, or 1080p
    aspect_ratiostringNoAspect ratio: 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, or adaptive
    generate_audiobooleanNoWhether to generate audio
    seedintegerNoRandom seed, -1 to 4294967295; same seed does not guarantee identical output
    sizestringNoExact output size, e.g. 1280x720
    input_referencesarrayNoOptional reference media array for image-to-video, first/last frame driving, video style transfer, or audio-driven generation
    input_references\\\.typestringYesReference media type: image, video, or audio. Must match the selected role
    input_references\\\.urlstringYesHTTPS URL of the reference media
    input_references\\\.rolestringYesReference media purpose. Allowed values: first_frame (first-frame image), last_frame (last-frame image), reference (appearance reference image; influences generation without serving as the first frame or locking its position in the frame), reference_video (reference video), or reference_audio (reference audio)
    metadataobjectNoBusiness pass-through fields for auditing or source tagging
    webhook_urlstringNoCallback URL invoked when the task completes or fails

    Example

    json
    1        {2          "model": "bytedance/seedance-2.0",3          "prompt": "A golden retriever running on a sunny beach, cinematic camera movement",4          "duration": 6,5          "resolution": "720p",6          "aspect_ratio": "16:9",7          "generate_audio": false,8          "seed": -1,9          "input_references": [10            {11              "type": "image",12              "url": "https://cdn.example.com/portrait.jpg",13              "role": "first_frame"14            }15          ],16          "metadata": {17            "source": "playground"18          },19          "webhook_url": "https://example.com/webhooks/gateai-video"20        }

    Response Fields

    NameTypeDescription
    job_idstringUnique job ID
    statusstringTask status: pending / in_progress / completed / failed
    modelstringModel used
    status_urlstringURL to poll task status
    messagestringServer message
    current_balancestringCurrent account balance (USD)
    estimated_coststringEstimated cost
    pre_deduct_amountstringPre-deducted display amount
    balance_after_estimatestringBalance after applying estimated cost
    currencystringCurrency, currently USD
    billing_noticestringBilling notice

    Response Example

    json
    1        {2          "code": 200,3          "msg": "",4          "data": {5            "job_id": "video_abc123",6            "status": "in_progress",7            "model": "bytedance/seedance-2.0",8            "status_url": "https://api.gate.ai/api/v1/videos/video_abc123",9            "message": "视频任务已提交，请调用 status_url 查询生成进度。",10            "current_balance": "100.0000000000",11            "estimated_cost": "1.0800000000",12            "pre_deduct_amount": "1.0800000000",13            "balance_after_estimate": "98.9200000000",14            "currency": "USDT",15            "billing_notice": "视频生成完成后按实际任务结果扣款，提交后请保持余额充足。"16          }17        }

    Response

    StatusMeaningDescriptionSchema
    202AcceptedTask accepted and queued. Returns job_id for status polling.VideoSubmitResponse
    400Bad RequestParameter errorErrorResponse
    401UnauthorizedNot logged in or token invalidErrorResponse
    402Payment RequiredInsufficient balance. Response includes estimated cost and current balance.ErrorResponse
    429Too Many RequestsToo many requests. Please slow down.ErrorResponse
    500Internal Server ErrorInternal server errorErrorResponse

    Query Task Status

    GET/api/v1/videos/{job_id}

    Poll job status, progress, and billing info. Returns download_url when status is completed.

    Request Parameters

    NameInTypeRequiredDescription
    job_idpathstringYesVideo task ID
    AuthorizationheaderstringYesGate.AI API Key. Format: Bearer <API_KEY>

    Response Fields

    NameTypeDescription
    job_idstringUnique job ID
    statusstringTask status: pending / in_progress / completed / failed
    modelstringModel used
    status_urlstringURL to poll task status
    download_urlstringVideo download URL (appears when status is completed)
    durationintegerVideo duration in seconds
    resolutionstringOutput resolution
    aspect_ratiostringAspect ratio
    generate_audiobooleanWhether audio is included
    estimated_coststringEstimated cost
    billed_coststringActual billed amount
    billing_statusstringBilling status: pre_deducted or settled
    expires_atstring(ISO 8601)Video file expiration time
    created_atstring(ISO 8601)Task creation time
    completed_atstring(ISO 8601)Task completion time

    Response Example

    json
    1        {2          "code": 200,3          "msg": "",4          "data": {5            "job_id": "video_abc123",6            "status": "completed",7            "model": "bytedance/seedance-2.0",8            "status_url": "https://api.gate.ai/api/v1/videos/video_abc123",9            "download_url": "https://api.gate.ai/api/v1/videos/video_abc123/content",10            "duration": 6,11            "resolution": "720p",12            "aspect_ratio": "16:9",13            "generate_audio": false,14            "estimated_cost": "1.0800000000",15            "billed_cost": "1.0800000000",16            "billing_status": "settled",17            "expires_at": "2026-06-26T05:00:00Z",18            "created_at": "2026-05-27T05:00:00Z",19            "completed_at": "2026-05-27T05:03:00Z"20          }21        }

    Response

    StatusMeaningDescriptionSchema
    200OKSuccessVideoStatusResponse
    401UnauthorizedNot logged in or token invalidErrorResponse
    404Not FoundJob not found, or job does not belong to this API key.ErrorResponse
    500Internal Server ErrorInternal server errorErrorResponse

    Download Video

    GET/api/v1/videos/{job_id}

    /contentAuthenticate and redirect (302) to the temporary video file URL.

    Request Parameters

    NameInTypeRequiredDescription
    job_idpathstringYesVideo task ID
    AuthorizationheaderstringYesGate.AI API Key. Format: Bearer <API_KEY>

    Response Example

    json
    1        HTTP/1.1 302 Found2        Location: https://cdn.example.com/videos/video_abc123.mp4?expires=1780000000

    Response

    StatusMeaningDescriptionSchema
    302FoundRedirects to temporary video download URL.
    401UnauthorizedNot logged in or token invalidErrorResponse
    404Not FoundJob not found, or job does not belong to this API key.ErrorResponse
    409ConflictTask not yet completed; video is not available for download.ErrorResponse
    410GoneVideo content has expired and is no longer available.ErrorResponse
    500Internal Server ErrorInternal server errorErrorResponse