Generate Videos

API Information

• URL: POST https://gateway.apimall.ai/api/v1/videos/generate
• Content-Type: application/json

Request Parameters

Request Example

{
  "model": "sora2",
  "type": "text-to-video",
  "prompt": "A cinematic drone shot of a futuristic city at sunrise.",
  "aspect_ratio": "landscape",
  "n_frames": "10",
  "remove_watermark": false
}

Response Example

{
  "success": true,
  "data": {
    "task_id": "vid_01HQ9MA3M6V6HC6S5R9V7N4Q4D",
    "request_id": "provider_req_01HQ9MAGWQJZ0RZN6G40YRMN6E",
    "credits_used": 30,
    "remaining_credits": 90,
    "model": "sora2"
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}

cURL Example

curl --request POST 'https://gateway.apimall.ai/api/v1/videos/generate' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "sora2",
  "type": "text-to-video",
  "prompt": "A cinematic drone shot of a futuristic city at sunrise.",
  "aspect_ratio": "landscape",
  "n_frames": "10",
  "remove_watermark": false
}'

JavaScript Example

const API_KEY = process.env.APIMALL_API_KEY;
const CREATE_URL = 'https://gateway.apimall.ai/api/v1/videos/generate';

const payload = {
  "model": "sora2",
  "type": "text-to-video",
  "prompt": "A cinematic drone shot of a futuristic city at sunrise.",
  "aspect_ratio": "landscape",
  "n_frames": "10",
  "remove_watermark": false
};

async function createTask() {
  const response = await fetch(CREATE_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    throw new Error(`Create task failed: ${response.status} ${response.statusText}`);
  }

  const json = await response.json();
  const taskId = json.data?.task_id;

  if (!taskId) {
    throw new Error('Missing task_id in create response');
  }

  return taskId;
}

async function getTask(taskId) {
  const response = await fetch(`https://gateway.apimall.ai/api/v1/videos/${encodeURIComponent(String(taskId))}`, {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  });

  if (!response.ok) {
    throw new Error(`Query task failed: ${response.status} ${response.statusText}`);
  }

  const json = await response.json();
  return {
    ...json,
  };
}

async function waitForTask(taskId) {
  while (true) {
    const task = await getTask(taskId);
    const state = task.data?.status;

    if (state === 'completed') {
      return task;
    }

    if (state === 'failed') {
      throw new Error(task.data?.failMsg || 'Task failed');
    }

    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

(async () => {
  const taskId = await createTask();
  const result = await waitForTask(taskId);
  console.log(result);
})().catch(console.error);

Response Parameters

Error Response Example

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits"
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}

API Information

• URL: GET https://gateway.apimall.ai/api/v1/videos/{task_id}

Path Parameters

Request Example

GET https://gateway.apimall.ai/api/v1/videos/vid_01HQ9MA3M6V6HC6S5R9V7N4Q4D

cURL Example

curl --request GET 'https://gateway.apimall.ai/api/v1/videos/vid_01HQ9MA3M6V6HC6S5R9V7N4Q4D' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response Example

{
  "success": true,
  "data": {
    "task_id": "vid_01HQ9MA3M6V6HC6S5R9V7N4Q4D",
    "model": "sora2",
    "status": "completed",
    "output": {
      "resultUrls": [
        "https://cdn.apimall.ai/generated/video-01.mp4"
      ]
    },
    "video_url": "https://cdn.apimall.ai/generated/result.mp4",
    "error_message": null,
    "credits_used": 30,
    "credits_refunded": 0,
    "created_at": "2026-03-12T09:35:00.000Z",
    "updated_at": "2026-03-12T09:36:48.000Z",
    "completed_at": "2026-03-12T09:36:48.000Z"
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}

Response Parameters

Common Error Codes