Video Generation

Generate videos from text or images using asynchronous APIs

The Video Generation API enables you to turn images or text prompts into videos.

Endpoint

POST /api/ai/videos

Request Format

Just like the Image API, the Video API seamlessly supports both JSON and multipart/form-data, allowing you to upload local images as reference frames without base64 conversion.

Request Parameters

prompt (String, Required)

The textual description for the video. Max length: 3000 characters.

model (String, Required)

The video generation model.

image (File/URL, Optional)

Reference images for video generation (e.g., first frame / last frame). Supports array of files in multipart/form-data.

size (String, Optional)

Output dimensions.

webhookUrl (String, Optional)

Highly Recommended. A URL that will receive a POST request with the final video URL and taskCostTime once generation is complete.

callback_url (String, Optional)

Alias for webhookUrl.

Example Request

curl -X POST "https://qxan.net/api/ai/videos" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Make the water in this painting flow",
"model": "runninghub-i2v-v1",
"image": ["https://example.com/path/to/start-frame.jpg"],
"webhookUrl": "https://your-server.com/webhook/video"
}'

curl -X POST "https://qxan.net/api/ai/videos" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "prompt=Make the water in this painting flow" \
-F "model=runninghub-i2v-v1" \
-F "image=@/path/to/start-frame.jpg"

const formData = new FormData();
formData.append("prompt", "Make the water in this painting flow");
formData.append("model", "runninghub-i2v-v1");
formData.append("image", fileInput.files[0]); // Upload image as start frame

const response = await fetch('https://qxan.net/api/ai/videos', {
method: 'POST',
headers: {
'Authorization': \`Bearer YOUR_API_KEY\`
},
body: formData
});

const data = await response.json();
console.log("Task ID:", data.id);

Example Responses

Upon successfully submitting a task, you will receive a response containing the task identifier.

{
  "id": "2044657634195480577",
  "status": "pending",
  "message": "Task queued successfully. Use the Task ID to query the status."
}

Best Practices

To handle video generations efficiently:

1. Submit the request to /api/ai/videos and store the returned id.
2. Retrieve the result:
   • Option A (Polling): Continuously call the Task Status API every 5 seconds using the id.
   • Option B (Webhook): Provide a webhookUrl in the initial request. Our server will ping your URL when the task completes.

Webhook Callback Details

When the task completes (success or failure), our system will send a POST request to your configured webhookUrl.

Success Response

{
  "id": "2044657634195480577",
  "object": "task_result",
  "created": 1709880000,
  "status": "success",
  "result": {
    "images": [
      {
        "fileUrl": "https://rh-images.xiaoyaoyou.com/1fed4ce62b6a35e17d9103980f90ef6a/output/ComfyUI_00001_ynbbq_1776760390.png",
        "fileType": "png"
      }
    ]
  },
  "error": null
}

Failure Response

{
  "id": "2044657634195480577",
  "object": "task_result",
  "created": 1709880000,
  "status": "failed",
  "result": {
    "images": []
  },
  "error": "Task processing failed: insufficient resources"
}

Field Description