Video Generation API

Video Generation

Video generation is asynchronous: create a task, then poll for the result. Supports timeout and cancellation.

Step 1: Create Task

POST https://shark.ai/api/v1/videos

Parameters vary by model. Common fields:

Parameter	Type	Required	Description
model	string	✓	Model ID
prompt	string	✓	Video description
duration	integer		Duration in seconds
resolution	string		e.g. 480p, 720p, 1080p
aspect_ratio	string		e.g. 16:9, 9:16, 1:1
frame_images	array		First/last frame images for image-to-video
seed	integer		Random seed (-1 for random)
timeout	integer		Max wait time in seconds (60-3600, default 600)

Create Response (202)

{
  "id": "task-uuid",
  "status": "pending",
  "polling_url": "/api/v1/videos/task-uuid"
}

Step 2: Poll Status

GET https://shark.ai/api/v1/videos/:id

Poll every 3-5 seconds until status is completed or failed.

Status Values

Status	Description
pending	Task created, waiting to start
running	Video is being generated
completed	Video ready, URLs available in output
failed	Generation failed, check error field
cancelled	Cancelled by user

Completed Response

{
  "id": "task-uuid",
  "status": "completed",
  "output": {
    "urls": [
      "https://cdn.example.com/video.mp4?sign=..."
    ]
  },
  "credit": 4000
}

Failed Response

{
  "id": "task-uuid",
  "status": "failed",
  "error": "Content was blocked by the safety system."
}

Step 3: Cancel Task (optional)

POST https://shark.ai/api/v1/videos/:id/cancel

Cancel a pending task. Only tasks in pending status can be cancelled. Returns 409 if already started.

{
  "id": "task-uuid",
  "status": "cancelled"
}

Image-to-Video

To generate video from a reference image, include frame_images with the image URL and frame type:

{
  "model": "alibaba/wan-2.7",
  "prompt": "The person walks toward the camera",
  "frame_images": [
    {
      "image_url": "https://example.com/photo.jpg",
      "frame_type": "first_frame"
    }
  ],
  "duration": 5,
  "resolution": "720p"
}

Supported frame types: first_frame, last_frame.

Code Examples

import requests, time

BASE = "https://shark.ai"
HEADERS = {"Authorization": "Bearer <api-key>", "Content-Type": "application/json"}

# Step 1: Create task
task = requests.post(f"{BASE}/api/v1/videos", headers=HEADERS, json={
    "model": "alibaba/wan-2.7",
    "prompt": "A serene mountain landscape at sunset",
    "duration": 5,
    "resolution": "720p",
}).json()
print("Task ID:", task["id"])

# Step 2: Poll for result
while True:
    r = requests.get(f"{BASE}/api/v1/videos/{task['id']}", headers=HEADERS).json()
    if r["status"] == "completed":
        print("Video URL:", r["output"]["urls"][0])
        break
    if r["status"] == "failed":
        print("Error:", r.get("error"))
        break
    print(f"Status: {r['status']}...")
    time.sleep(3)

See model list for available video models and their parameter schemas.