Video Generation API

Endpoints for creating, retrieving, and managing AI-generated videos.

Generate Video

Start a new video generation task.

POST /api/v1/video/generate

Request Body

{
  "prompt": "A golden retriever running through a sunlit meadow, cinematic slow motion",
  "model": "sora-2",
  "duration": 10,
  "aspectRatio": "16:9",
  "quality": "720p",
  "startImageUrl": "https://example.com/image.jpg"
}

Field	Type	Required	Description
prompt	string	Yes	Text description of the video to generate
model	string	Yes	AI model to use (sora-2, veo-3-1, wan-2-6, seedance-1-5)
duration	number	Yes	Video duration in seconds (model-dependent range)
aspectRatio	string	Yes	Output aspect ratio (16:9, 9:16, 1:1, etc.)
quality	string	No	Output quality (480p, 720p, 1080p, 4k)
startImageUrl	string	No	URL of a reference image for image-to-video generation

Response

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PENDING",
    "model": "sora-2",
    "creditsUsed": 2,
    "createdAt": "2026-03-13T10:00:00.000Z"
  }
}

Errors

Status	Cause
400	Invalid parameters (unsupported model, duration out of range, etc.)
401	Not authenticated
402	Insufficient credits

Video Generation Flow

1. The API validates your request and checks credit balance.
2. Credits are frozen (reserved but not yet consumed).
3. The task is sent to the AI provider for asynchronous processing.
4. The API returns immediately with a PENDING status and UUID.
5. Use the Get Task Status endpoint to poll for completion.
6. On success, credits are settled (consumed). On failure, credits are released (returned).

---

List Videos

Retrieve a paginated list of the authenticated user's videos.

GET /api/v1/video/list?page=1&pageSize=20

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
pageSize	number	20	Items per page

Response

{
  "success": true,
  "data": {
    "videos": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "prompt": "A golden retriever running...",
        "model": "sora-2",
        "status": "COMPLETED",
        "videoUrl": "https://cdn.example.com/video.mp4",
        "thumbnailUrl": "https://cdn.example.com/thumb.jpg",
        "duration": 10,
        "aspectRatio": "16:9",
        "creditsUsed": 2,
        "createdAt": "2026-03-13T10:00:00.000Z",
        "completedAt": "2026-03-13T10:03:00.000Z"
      }
    ],
    "total": 42,
    "page": 1,
    "pageSize": 20
  }
}

---

Get Video

Retrieve details for a specific video by UUID.

GET /api/v1/video/{uuid}

Response

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "prompt": "A golden retriever running...",
    "model": "sora-2",
    "status": "COMPLETED",
    "provider": "evolink",
    "videoUrl": "https://cdn.example.com/video.mp4",
    "thumbnailUrl": "https://cdn.example.com/thumb.jpg",
    "startImageUrl": null,
    "duration": 10,
    "resolution": "720p",
    "aspectRatio": "16:9",
    "fileSize": 15728640,
    "creditsUsed": 2,
    "generationTime": 180,
    "createdAt": "2026-03-13T10:00:00.000Z",
    "completedAt": "2026-03-13T10:03:00.000Z"
  }
}

---

Delete Video

Soft-delete a video (marks it as deleted but retains the record).

DELETE /api/v1/video/{uuid}

Response

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "deleted": true
  }
}

---

Get Task Status

Poll the generation status of a video task.

GET /api/v1/video/task?uuid={uuid}

Query Parameters

Parameter	Type	Required	Description
uuid	string	Yes	Video UUID from the generate response

Response

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "GENERATING",
    "progress": 65
  }
}

Video Statuses

Status	Description
PENDING	Task created, waiting to be picked up by AI provider
GENERATING	AI provider is actively generating the video
UPLOADING	Video generated, being uploaded to storage
COMPLETED	Video is ready for viewing and download
FAILED	Generation failed (credits are automatically released)

---

Get Available Models

Retrieve the list of AI models available for video generation.

GET /api/v1/config/models

Response

{
  "success": true,
  "data": {
    "models": [
      {
        "id": "sora-2",
        "name": "Sora 2",
        "provider": "OpenAI",
        "modes": ["text-to-video", "image-to-video"],
        "maxDuration": 15,
        "resolutions": ["720p", "1080p"],
        "aspectRatios": ["16:9", "9:16"],
        "enabled": true
      }
    ]
  }
}