Generate Veo3.1 Video

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /jobs/createTask

Full URL: https://ai.modelfold.online/v1/jobs/createTask

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

WARNING

This is the new version of the API documentation; for the old version of the API, please see https://ai.modelfold.online/docs/en/veo3-api/generate-veo-3-video.

Veo 3.1 Generation API

Our Veo 3.1 Generation API is more than a direct wrapper around Google's baseline. It layers extensive optimisation and reliability tooling on top of the official models, giving you greater flexibility and markedly higher success rates (see ai.modelfold.online/pricing for full details).

Capability	Details
Models	• Veo 3.1 Quality — flagship model, highest fidelity• Veo 3.1 Fast — cost-efficient variant that still delivers strong visual results• Veo 3.1 Lite — most cost-effective model for high-volume generation
Tasks	• Text → Video• Image → Video (single reference frame or first and last frames)• Material → Video (based on material images)
Generation Modes	• TEXT_2_VIDEO — Text-to-video: using text prompts only• FIRST_AND_LAST_FRAMES_2_VIDEO — First and last frames to video: generate transition videos using one or two images• REFERENCE_2_VIDEO — Material-to-video: based on material images (Fast model and Lite model, supports 16:9 & 9:16)
Aspect Ratios	Supports both native 16:9 and 9:16 outputs. Auto mode lets the system decide aspect ratio based on input materials and internal strategy (for production control, we recommend explicitly setting aspect_ratio).
Output Quality	Both 16:9 and 9:16 support 1080P and 4K outputs.
Audio Track	All videos ship with background audio by default. In rare cases, audio may be suppressed when the scene is deemed sensitive (e.g. minors).

Why our Veo 3.1 API is different

1. True vertical video – Native Veo 3.1 supports 9:16 output, delivering authentic vertical videos without the need for re-framing or manual editing.
2. Global language reach – Our flow supports multilingual prompts by default (no extra configuration required).
3. Significant cost savings – see ai.modelfold.online/pricing for current prices.

TIP

Choosing 1080p or 4k at generation costs the 720p price plus the 1080P / 4K upgrade price. For current prices, see ai.modelfold.online/pricing.

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
model	string	Yes	Must be "veo-3-1". Use input.model to choose the Fast / Lite / Quality tier. Default："veo-3-1"。 Allowed values：veo-3-1。 示例：veo-3-1。
callBackUrl	string	No	Completion callback URL for receiving video generation status updates. - Optional but recommended for production use - System will POST task completion status to this URL when the video generation is completed - Callback will include task results, video URLs, and status information - Your callback endpoint should accept POST requests with JSON payload - For detailed callback format and implementation guide, see Callback Documentation - Alternatively, poll Get Task Details (/market/common/get-task-detail). - To ensure callback security, see Webhook Verification Guide for signature verification implementation 示例：http://your-callback-url.com/complete。
input	object	Yes	—
input.prompt	string	Yes	Text prompt describing the desired video content. Required for all generation modes. - Should be detailed and specific in describing video content - Can include actions, scenes, style and other information - For image-to-video, describe how you want the image to come alive 示例：A dog playing in a park。
input.model	string	No	Veo 3.1 tier: "veo3_fast" (default), "veo3_lite" or "veo3" (Quality). The top-level model stays "veo-3-1". REFERENCE_2_VIDEO supports veo3_fast and veo3_lite. Default："veo3_fast"。 Allowed values：veo3_fast / veo3_lite / veo3。 示例：veo3_fast。
input.image_urls	array<string>	No	Image URLs. FIRST_AND_LAST_FRAMES_2_VIDEO: 1 image (first frame) or 2 images (first + last frame). REFERENCE_2_VIDEO: 1–3 reference images, 8-second duration only.
input.generation_type	string	No	Video generation mode (optional). Specifies different video generation approaches: - TEXT_2_VIDEO: Text-to-video - Generate videos using only text prompts - FIRST_AND_LAST_FRAMES_2_VIDEO: First and last frames to video - Flexible image-to-video generation mode - 1 image: Generate video based on the provided image - 2 images: First image as first frame, second image as last frame, generating transition video - REFERENCE_2_VIDEO: Reference-to-video - Generate videos based on reference images, requires 1-3 images in imageUrls (minimum 1, maximum 3) Important Notes: - REFERENCE_2_VIDEO mode currently supports the veo3_fast and veo3_lite models. - If not specified, the system will automatically determine the generation mode based on whether imageUrls are provided Allowed values：TEXT_2_VIDEO / FIRST_AND_LAST_FRAMES_2_VIDEO / REFERENCE_2_VIDEO。 示例：TEXT_2_VIDEO。
input.aspect_ratio	string	No	Video aspect ratio. Specifies the dimension ratio of the generated video. Available options: - 16:9: Landscape video format. - 9:16: Portrait video format, suitable for mobile short videos - Auto: In auto mode, the video will be automatically center-cropped based on whether your uploaded image is closer to 16:9 or 9:16. Default value is 16:9. Default："16:9"。 Allowed values：16:9 / 9:16 / Auto。 示例：16:9。
input.enable_fallback	boolean	No	Deprecated. Remove it from requests. Default：false。 示例：false。
input.enable_translation	boolean	No	Optional. When true, the prompt is translated to English before generation. 示例：true。
input.watermark	string	No	Watermark text. - Optional parameter - If provided, a watermark will be added to the generated video 示例：MyBrand。
input.resolution	string	No	Output resolution: 720p (default), 1080p or 4k. For 1080p and 4k, the video URL is in resultJson.data.result_urls (the 720p version is in data.origin_urls). Controls the pixel dimensions of the generated video. Higher resolution results in greater clarity and detail, while lower resolution allows for faster generation. Default："720p"。 Allowed values：720p / 1080p / 4k。 示例：720p。
input.duration	integer	No	The duration of the generated video, in seconds. Optional values are 4, 6, 8. Important Note: - The REFERENCE_2_VIDEO mode currently only supports a duration of 8 seconds. Default：8。 Allowed values：4 / 6 / 8。 示例：8。

Request Example

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "veo-3-1",
  "callBackUrl": "http://your-callback-url.com/complete",
  "input": {
    "prompt": "A dog playing in a park",
    "image_urls": [
      "http://example.com/image1.jpg",
      "http://example.com/image2.jpg"
    ],
    "watermark": "MyBrand",
    "aspect_ratio": "16:9",
    "enable_translation": true,
    "generation_type": "REFERENCE_2_VIDEO"
  }
}'

{
  "model": "veo-3-1",
  "callBackUrl": "http://your-callback-url.com/complete",
  "input": {
    "prompt": "A dog playing in a park",
    "image_urls": [
      "http://example.com/image1.jpg",
      "http://example.com/image2.jpg"
    ],
    "watermark": "MyBrand",
    "aspect_ratio": "16:9",
    "enable_translation": true,
    "generation_type": "REFERENCE_2_VIDEO"
  }
}

Response

200 — Request successful

参数	类型	必填	说明
code	integer	否	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：200 / 400 / 401 / 402 / 404 / 422 / 429 / 455 / 500 / 501 / 505。 示例：200。
msg	string	否	Error message when code != 200 示例：success。
data	object	否	—
data.taskId	string	否	Task ID, can be used with Get Task Details endpoint to query task status 示例：veo_task_abcdef123456。

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "veo_task_abcdef123456"
  }
}

500 — Server error.

参数	类型	必填	说明
code	integer	是	Response status code - 200: Success - Request has been processed successfully - 401: Unauthorized - Authentication credentials are missing or invalid - 402: Insufficient Credits - Account does not have enough credits to perform the operation - 404: Not Found - The requested resource or endpoint does not exist - 408: Timeout - No result has been returned for over 10 minutes. - 422: Validation Error - The request parameters failed validation checks - 429: Rate Limited - Request limit has been exceeded for this resource - 455: Service Unavailable - System is currently undergoing maintenance - 500: Server Error - An unexpected error occurred while processing the request - 501: Generation Failed - Content generation task failed - 505: Feature Disabled - The requested feature is currently disabled
msg	string	是	Response message, error description when failed
data	object	是	—

{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}

Callback

onVideoGenerated

Callback URL: {$request.body#/callBackUrl} (the callBackUrl in the request body).

When the video generation task is completed, the system will send the result to your provided callback URL via POST request

Callback body parameters

参数	类型	必填	说明
code	integer	否	Status code - 200: Success - Video generation task successfully - 400: Your prompt was flagged by Website as violating content policies. Failed to fetch the image. Kindly verify any access limits set by you or your service provider. public error unsafe image upload. - 500: Internal Error, Please try again later. Internal Error - Timeout - 501: Failed - Video generation task failed Allowed values：200 / 400 / 500 / 501。 示例：200。
msg	string	否	Status message 示例：Veo3.1 video generated successfully.。
data	object	否	—
data.taskId	string	否	Task ID 示例：veo_task_abcdef123456。
data.info	object	否	—
data.info.resultUrls	array<string>	否	Generated video URLs
data.info.originUrls	array<string>	否	Original video URLs. Only has value when aspect_ratio is not 16:9
data.info.resolution	string	否	Video resolution information 示例：1080p。

{
  "code": 200,
  "msg": "Veo3.1 video generated successfully.",
  "data": {
    "taskId": "veo_task_abcdef123456",
    "info": {
      "resultUrls": [
        "http://example.com/video1.mp4"
      ],
      "originUrls": [
        "http://example.com/original_video1.mp4"
      ],
      "resolution": "1080p"
    }
  }
}