Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vmeg.ai/llms.txt

Use this file to discover all available pages before exploring further.

Materials are uploaded directly to CDN/object storage via presigned URLs, then registered with the VMEG API. Bytes do not pass through the API gateway. Every upload-related POST in this flow requires X-Idempotency-Key.

​
Choose an upload mode

ModeWhen to use
Single-file (presigned URL)Smaller files, one PUT
MultipartLarge files, resumable parts
Request and response fields: Generate presigned upload URL, Complete single-file upload, and other Assets - Materials → upload operations in API reference.

​
Single-file upload

1

Get presigned URL

POST /openapi/v1/assets/material/upload/gen-upload-url with fileHash (MD5) and fileName.
2

PUT file to CDN

If the response includes data.material, the file was deduplicated — skip PUT. Otherwise upload bytes to data.uploadUrl.
3

Complete upload

POST /openapi/v1/assets/material/upload/complete with s3Uri, materialId, fileHash, and fileName from the gen-upload-url step.

​
Example

import crypto from "node:crypto";
import fs from "node:fs";

const API_BASE = "https://api.vmeg.ai";
const API_KEY = process.env.VMEG_API_KEY;
const FILE_PATH = "./demo.mp4";

function md5File(path) {
  const hash = crypto.createHash("md5");
  hash.update(fs.readFileSync(path));
  return hash.digest("hex");
}

function idemKey(step) {
  return `upload-${step}-${crypto.randomUUID()}`;
}

async function apiPost(path, body) {
  const res = await fetch(`${API_BASE}${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      "X-Idempotency-Key": idemKey(path),
    },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (json.code !== 200) throw new Error(json.message || "API error");
  return json.data;
}

async function uploadSingleFile() {
  const fileName = FILE_PATH.split("/").pop();
  const fileHash = md5File(FILE_PATH);
  const fileBytes = fs.readFileSync(FILE_PATH);

  const gen = await apiPost("/openapi/v1/assets/material/upload/gen-upload-url", {
    fileHash,
    fileName,
  });

  if (gen.material?.materialId) {
    console.log("Instant upload (dedup):", gen.material.materialId);
    return gen.material.materialId;
  }

  const putRes = await fetch(gen.uploadUrl, { method: "PUT", body: fileBytes });
  if (!putRes.ok) throw new Error(`CDN PUT failed: ${putRes.status}`);

  const material = await apiPost("/openapi/v1/assets/material/upload/complete", {
    s3Uri: gen.s3Uri,
    materialId: gen.materialId,
    fileHash,
    fileName,
  });

  console.log("materialId:", material.materialId);
  return material.materialId;
}

uploadSingleFile().catch(console.error);
The Java example uses Jackson (ObjectMapper) for JSON. Add com.fasterxml.jackson.core:jackson-databind to your project, or parse responses with your preferred JSON library.

​
Multipart upload

For large files:
  1. POST .../multipart/initiate
  2. POST .../multipart/presign-parts — presigned URL per part
  3. PUT each part to CDN and record each part ETag
  4. POST .../multipart/complete — finalize and get materialId
  5. On failure: POST .../multipart/abort
Use recommendedPartSize from the initiate response (S3 minimum part size is typically 5 MB except the last part).

​
Example

import crypto from "node:crypto";
import fs from "node:fs";

const API_BASE = "https://api.vmeg.ai";
const API_KEY = process.env.VMEG_API_KEY;
const FILE_PATH = "./large.mp4";

function md5File(path) {
  const hash = crypto.createHash("md5");
  hash.update(fs.readFileSync(path));
  return hash.digest("hex");
}

function idemKey(step) {
  return `multipart-${step}-${crypto.randomUUID()}`;
}

async function apiPost(path, body) {
  const res = await fetch(`${API_BASE}${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      "X-Idempotency-Key": idemKey(path),
    },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (json.code !== 200) throw new Error(json.message || "API error");
  return json.data;
}

function readPart(buffer, offset, size) {
  return buffer.subarray(offset, Math.min(offset + size, buffer.length));
}

async function uploadMultipart() {
  const fileName = FILE_PATH.split("/").pop();
  const fileHash = md5File(FILE_PATH);
  const fileBytes = fs.readFileSync(FILE_PATH);

  const init = await apiPost("/openapi/v1/assets/material/upload/multipart/initiate", {
    fileHash,
    fileName,
  });

  const partSize = init.recommendedPartSize || 8 * 1024 * 1024;
  const partNumbers = [];
  for (let offset = 0, n = 1; offset < fileBytes.length; offset += partSize, n++) {
    partNumbers.push(n);
  }

  const presign = await apiPost(
    "/openapi/v1/assets/material/upload/multipart/presign-parts",
    {
      materialId: init.materialId,
      uploadId: init.uploadId,
      fileHash,
      fileName,
      partNumbers,
    }
  );

  const parts = [];
  for (const { partNumber, url } of presign.urls) {
    const start = (partNumber - 1) * partSize;
    const chunk = readPart(fileBytes, start, partSize);
    const putRes = await fetch(url, { method: "PUT", body: chunk });
    if (!putRes.ok) throw new Error(`Part ${partNumber} PUT failed: ${putRes.status}`);
    const eTag = (putRes.headers.get("etag") || "").replace(/"/g, "");
    parts.push({ partNumber, eTag });
  }

  const material = await apiPost(
    "/openapi/v1/assets/material/upload/multipart/complete",
    {
      materialId: init.materialId,
      uploadId: init.uploadId,
      fileHash,
      fileName,
      parts,
    }
  );

  console.log("materialId:", material.materialId);
  return material.materialId;
}

uploadMultipart().catch(console.error);

​
After upload

Use materialId in source.materialId for media translation. Manage assets via Materials.