API Reference

Base URL: https://aivideomaker.ai

Authentication

All requests require an API key passed in the request header:

Header	Required	Description
key	Yes	Your API key

---

Endpoints

1. Create generation task

POST /api/v1/generate/{model}

Create a video generation task. Returns a task ID and URLs for querying / cancelling.

Request headers

Header	Required	Description
key	Yes	Your API key
webhookUrl	No	Callback URL for task status notifications

Path parameter

Parameter	Required	Allowed values
model	Yes	t2v / i2v / lv / t2v_v3 / i2v_v3

---

Model parameters

t2v — Text to Video

Field	Type	Required	Description
prompt	string	Yes	Text prompt describing the video
aspectRatio	string	Yes	16:9 / 9:16 / 1:1
duration	string	Yes	5 or 8 (seconds)

Credits: duration × 1

Example request

POST /api/v1/generate/t2v

{
  "prompt": "A cinematic sunset over a futuristic city skyline",
  "aspectRatio": "16:9",
  "duration": "8"
}

---

i2v — Image to Video

Field	Type	Required	Description
image	string	Yes	Public image URL or data:image/...;base64,...
prompt	string or null	No	Optional text prompt
duration	string	Yes	5 or 8 (seconds)

Credits: duration × 1

---

lv — Long Video

Field	Type	Required	Description
image	string	Yes	First-frame image URL or data:image/...;base64,...
prompt	string[]	Yes	Array of segment prompts, max 6 items

Credits: number of prompts × 5 × 15

Duration is calculated automatically: each prompt segment = 5 seconds.

---

t2v_v3 — Text to Video V3

Field	Type	Required	Description
prompt	string	Yes	Text prompt
aspectRatio	string	Yes	16:9 / 9:16 / 1:1
duration	string	Yes	5 / 10 / 15 / 20 (seconds)

Credits: duration × 10

---

i2v_v3 — Image to Video V3

Field	Type	Required	Description
image	string	Yes	Public image URL or data:image/...;base64,...
prompt	string or null	No	Optional text prompt
duration	string	Yes	5 / 10 / 15 / 20 (seconds)

Credits: duration × 10

---

Success response

{
  "status": "SUBMITTED",
  "taskId": "ckxxxxxxxx",
  "responseUrl": "https://aivideomaker.ai/api/v1/tasks/ckxxxxxxxx",
  "statusUrl": "https://aivideomaker.ai/api/v1/tasks/ckxxxxxxxx/status",
  "cancelUrl": "https://aivideomaker.ai/api/v1/tasks/ckxxxxxxxx/cancel"
}

Error response

{
  "status": "FAILED",
  "message": "Insufficient credits"
}

---

2. List tasks

GET /api/v1/tasks

Returns all tasks under the current API key, sorted by creation time (newest first).

Response example

{
  "tasks": [
    {
      "id": "ckxxxxxxxx",
      "createdAt": "2026-03-19T08:00:00.000Z",
      "model": "t2v",
      "input": { "prompt": "...", "aspectRatio": "16:9" },
      "output": null,
      "status": "PROGRESS",
      "completedAt": null
    }
  ]
}

---

3. Get task details

GET /api/v1/tasks/{taskId}

Returns full task information including input, output, status, and completion time.

---

4. Get task status

GET /api/v1/tasks/{taskId}/status

Returns the current task status only. Ideal for polling.

Response

{
  "status": "COMPLETED"
}

---

5. Cancel task

PUT /api/v1/tasks/{taskId}/cancel

Cancel a task. Only works when the task is still in SUBMITTED status.

---

Task status values

Status	Description
SUBMITTED	Task submitted, waiting to be processed
PROGRESS	Task is being processed
COMPLETED	Task finished successfully
FAILED	Task failed (credits are refunded automatically)
CANCEL	Task was cancelled

Rate limiting

Task query endpoints are rate-limited to 60 requests per minute per IP. When exceeded, the API returns HTTP 429 with a Retry-After header.