ModelFold Docs

English

简体中文

English

简体中文

Appearance

Grok Imagine Image to 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.

Output is an MP4 video with an audio track generated together with the video (dialogue written in the prompt is spoken). Audio cannot be turned off.

Query Task Status ​

After submitting a task, use the unified query endpoint to check progress and retrieve results:

  • Get Task Details — Learn how to query task status and retrieve generation results

TIP

For production use, we recommend using the callBackUrl parameter to receive automatic notifications when generation completes, rather than polling the status endpoint.

Request Parameters ​

Body (application/json) ​

ParameterTypeRequiredDescription
modelstringYesThe model name to use for generation. Required field.
- Must be grok-imagine/image-to-video for this endpoint Default："grok-imagine/image-to-video"。 Allowed values：grok-imagine/image-to-video。 示例：grok-imagine/image-to-video。
callBackUrlstringNoThe URL to receive video generation task completion updates. Optional but recommended for production use.
- System will POST task status and results to this URL when video generation completes
- Callback includes generated video URLs and task information
- Your callback endpoint should accept POST requests with JSON payload containing video results
- Alternatively, use the Get Task Details endpoint to poll task status
- To ensure callback security, see Webhook Verification Guide for signature verification implementation 示例：https://your-domain.com/api/callback。
inputobjectYesInput parameters for the video generation task
  input.image_urlsarray&lt;string&gt;NoProvide an external image URL as a reference for video generation. Up to 7 images are supported. Do not use it simultaneously with task_id. In your prompt, reference an uploaded image by typing @image(n) followed by a space (for example: @image1 a sunset over the ocean).
- Supports JPEG, PNG, and WEBP formats
- Maximum file size for each image: 10MB
- The Spicy mode is not available when using external images
- The array can contain a maximum of seven URLs
- Only one is supported when the resolution is 1080p.
  input.task_idstringNoTask ID from a previously generated Grok image. Use with index to select a specific image. Do not use with image_urls.
- Use task ID from grok-imagine/text-to-image generations
- Supports all modes including Spicy
- Maximum length: 100 characters 示例：task_grok_12345678。
  input.indexintegerNoWhen using task_id, the 0-based index of the image to use. A grok-imagine/text-to-image task returns 2 images, so valid values are 0 and 1. Default 0.
- Ignored if image_urls is provided Default：0。 示例：0。
  input.promptstringNoText prompt describing the desired video motion. Optional field.
- Should be detailed and specific about the desired visual motion
- Describe movement, action sequences, camera work, and timing
- Include details about subjects, environments, and motion dynamics
- Maximum length: 5000 characters
- Supports English language prompts 示例：POV hand comes into frame handing the girl a cup of take away coffee, the girl steps out of the screen looking tired, then takes it and she says happily: "thanks! Back to work" she exits the frame and walks right to a different part of the office.。
  input.modestringNoSpecifies the generation mode affecting the style and intensity of motion. Note: Spicy mode is not available for external image inputs.
- fun: More creative and playful interpretation
- normal: Balanced approach with good motion quality
- spicy: More dynamic and intense motion effects (not available for external images)
Default: normal Default："normal"。 Allowed values：fun / normal / spicy。 示例：normal。
  input.durationstringNoThe duration of the generated video (in seconds) (6-30). (Minimum: 6, Maximum: 30, Step: 1)
  input.resolutionstringNoThe resolution of the generated video. Default："480p"。 Allowed values：480p / 720p / 1080p。 示例：480p。
  input.aspect_ratiostringNoImage ratio selection only applies to multi-image generation mode. In single-image mode, the video width and height are referenced to the image width and height. Default："16:9"。 Allowed values：2:3 / 3:2 / 1:1 / 16:9 / 9:16。 示例：16:9。
  input.nsfw_checkerbooleanNoDefaults to false. When false, no additional content filtering is applied and results are returned directly by the model.

Request Example ​

bash
curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "grok-imagine/image-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "image_urls": [
      "https://file.aiquickdraw.com/custom-page/akr/section-images/1762247692373tw5di116.png"
    ],
    "prompt": "POV hand comes into frame handing the girl a cup of take away coffee, the girl steps out of the screen looking tired, then takes it and she says happily: \"thanks! Back to work\" she exits the frame and walks right to a different part of the office.",
    "mode": "normal",
    "duration": "6",
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }
}'
json
{
  "model": "grok-imagine/image-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "image_urls": [
      "https://file.aiquickdraw.com/custom-page/akr/section-images/1762247692373tw5di116.png"
    ],
    "prompt": "POV hand comes into frame handing the girl a cup of take away coffee, the girl steps out of the screen looking tired, then takes it and she says happily: \"thanks! Back to work\" she exits the frame and walks right to a different part of the office.",
    "mode": "normal",
    "duration": "6",
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }
}

Response ​

200 — Request successful ​

json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "281e5b0*********************f39b9"
  }
}

Callback ​

videoTaskCompleted ​

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

The system sends this callback when the grok-imagine/image-to-video task succeeds or fails.

Callback body parameters

参数类型必填说明
codeinteger是Unified callback code: 200 for success, 501 for failure. Allowed values：200 / 501。 示例：200。
msgstring是Unified callback message. Allowed values：Playground task completed successfully. / Playground task failed.。 示例：Playground task completed successfully.。
dataobject是—
  data.taskIdstring是The unique task identifier.
  data.modelstring是The model used for the task. Allowed values：grok-imagine/image-to-video。 示例：grok-imagine/image-to-video。
  data.statestring是Terminal task state. Allowed values：success / fail。 示例：success。
  data.paramstring是JSON string containing the submitted task parameters.
  data.resultJsonstring否JSON string containing resultUrls, firstFrameUrl, lastFrameUrl, or resultObject when successful. Present only when state is success.
  data.failCodestring否Failure code, a numeric string such as "400" or "500". Present only when state is fail.
  data.failMsgstring否Failure reason. Present only when state is fail.
  data.costTimeinteger否Processing time in seconds. Present on both success and failure callbacks.
  data.completeTimeinteger否Task completion timestamp.
  data.createTimeinteger否Task creation timestamp.
  data.updateTimeinteger否Use completeTime as the completion time; updateTime may equal createTime.
  data.creditsConsumednumber否Credits consumed by the task; 0 for failed tasks.

Task completed successfully

json
{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "grok-imagine/image-to-video",
    "state": "success",
    "param": "{\"input\":\"{\\\"task_id\\\":\\\"task_grok_12345678\\\",\\\"image_urls\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"prompt\\\":\\\"POV hand comes into frame handing the girl a cup of take away coffee, the girl steps out of the screen looking tired,...\\\",\\\"mode\\\":\\\"normal\\\",\\\"duration\\\":\\\"6\\\",\\\"resolution\\\":\\\"480p\\\",\\\"aspect_ratio\\\":\\\"16:9\\\"}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"grok-imagine/image-to-video\"}",
    "resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
    "costTime": 12,
    "completeTime": 1234567890,
    "createTime": 1234560000,
    "updateTime": 1234567890,
    "creditsConsumed": 1.23
  }
}

Task failed

json
{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "grok-imagine/image-to-video",
    "state": "fail",
    "param": "{\"input\":\"{\\\"task_id\\\":\\\"task_grok_12345678\\\",\\\"image_urls\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"prompt\\\":\\\"POV hand comes into frame handing the girl a cup of take away coffee, the girl steps out of the screen looking tired,...\\\",\\\"mode\\\":\\\"normal\\\",\\\"duration\\\":\\\"6\\\",\\\"resolution\\\":\\\"480p\\\",\\\"aspect_ratio\\\":\\\"16:9\\\"}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"grok-imagine/image-to-video\"}",
    "failCode": "400",
    "failMsg": "<error detail>",
    "costTime": 12,
    "creditsConsumed": 0
  }
}

ModelFold — one API for all the best AI models.

© 2026 ModelFold