素材上传

素材通过 预签名 URL 直传 CDN/对象存储，再调用 VMEG API 完成注册。文件字节 不经过 API 网关。本流程中所有相关 POST 均须携带 X-Idempotency-Key。

获取预签名 URL 或分片发起等前置步骤可能已返回 materialId。该 ID 仅用于续传/完成上传，在整套上传流程结束前不要把它传给 create-async 或其他产品接口。只有在单文件 complete、分片 complete，或瞬时上传/去重响应中已返回已注册 material 之后，该 materialId 才能用于建任务。

选择上传方式

方式	适用场景
单文件（预签名 URL）	较小文件，一次 PUT
分片（Multipart）	大文件、可断点续传

请求与响应字段：获取预签名 URL、完成单文件上传，以及 API 参考中 Assets - Materials → upload 下的其他接口。

单文件上传

获取预签名 URL

POST /openapi/v1/assets/material/upload/gen-upload-url，传入 fileHash（MD5）与 fileName。

PUT 到 CDN

若响应含 data.material，表示文件已去重，无需 PUT；否则将字节上传到 data.uploadUrl。

完成上传

POST /openapi/v1/assets/material/upload/complete，使用 gen-upload-url 返回的 s3Uri、materialId、fileHash、fileName。

示例

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);

import hashlib
import os
import uuid

import requests

API_BASE = "https://api.vmeg.ai"
API_KEY = os.environ["VMEG_API_KEY"]
FILE_PATH = "./demo.mp4"


def md5_file(path: str) -> str:
    h = hashlib.md5()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(1024 * 1024), b""):
            h.update(chunk)
    return h.hexdigest()


def idem_key(step: str) -> str:
    return f"upload-{step}-{uuid.uuid4()}"


def api_post(path: str, body: dict) -> dict:
    res = requests.post(
        f"{API_BASE}{path}",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
            "X-Idempotency-Key": idem_key(path),
        },
        json=body,
        timeout=120,
    )
    res.raise_for_status()
    payload = res.json()
    if payload.get("code") != 200:
        raise RuntimeError(payload.get("message") or "API error")
    return payload["data"]


def upload_single_file() -> str:
    file_name = os.path.basename(FILE_PATH)
    file_hash = md5_file(FILE_PATH)

    gen = api_post(
        "/openapi/v1/assets/material/upload/gen-upload-url",
        {"fileHash": file_hash, "fileName": file_name},
    )

    if gen.get("material", {}).get("materialId"):
        material_id = gen["material"]["materialId"]
        print("Instant upload (dedup):", material_id)
        return material_id

    with open(FILE_PATH, "rb") as f:
        put = requests.put(gen["uploadUrl"], data=f, timeout=600)
    put.raise_for_status()

    material = api_post(
        "/openapi/v1/assets/material/upload/complete",
        {
            "s3Uri": gen["s3Uri"],
            "materialId": gen["materialId"],
            "fileHash": file_hash,
            "fileName": file_name,
        },
    )
    material_id = material["materialId"]
    print("materialId:", material_id)
    return material_id


if __name__ == "__main__":
    upload_single_file()

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.MessageDigest;
import java.time.Duration;
import java.util.Map;
import java.util.UUID;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public final class SingleMaterialUpload {
  private static final String API_BASE = "https://api.vmeg.ai";
  private static final String API_KEY = System.getenv("VMEG_API_KEY");
  private static final Path FILE_PATH = Path.of("demo.mp4");

  private static final HttpClient HTTP = HttpClient.newBuilder()
      .connectTimeout(Duration.ofSeconds(30))
      .build();
  private static final ObjectMapper JSON = new ObjectMapper();

  public static void main(String[] args) throws Exception {
    String materialId = uploadSingleFile();
    System.out.println("materialId: " + materialId);
  }

  static String uploadSingleFile() throws Exception {
    String fileName = FILE_PATH.getFileName().toString();
    String fileHash = md5File(FILE_PATH);
    byte[] fileBytes = Files.readAllBytes(FILE_PATH);

    JsonNode gen = apiPost(
        "/openapi/v1/assets/material/upload/gen-upload-url",
        Map.of("fileHash", fileHash, "fileName", fileName));

    if (gen.hasNonNull("material") && gen.get("material").hasNonNull("materialId")) {
      return gen.get("material").get("materialId").asText();
    }

    HttpRequest put = HttpRequest.newBuilder()
        .uri(URI.create(gen.get("uploadUrl").asText()))
        .PUT(HttpRequest.BodyPublishers.ofByteArray(fileBytes))
        .timeout(Duration.ofMinutes(10))
        .build();
    HttpResponse<Void> putRes = HTTP.send(put, HttpResponse.BodyHandlers.discarding());
    if (putRes.statusCode() < 200 || putRes.statusCode() >= 300) {
      throw new IOException("CDN PUT failed: " + putRes.statusCode());
    }

    JsonNode material = apiPost(
        "/openapi/v1/assets/material/upload/complete",
        Map.of(
            "s3Uri", gen.get("s3Uri").asText(),
            "materialId", gen.get("materialId").asText(),
            "fileHash", fileHash,
            "fileName", fileName));

    return material.get("materialId").asText();
  }

  static JsonNode apiPost(String path, Map<String, String> body) throws Exception {
    String bodyJson = JSON.writeValueAsString(body);
    HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create(API_BASE + path))
        .timeout(Duration.ofSeconds(120))
        .header("Authorization", "Bearer " + API_KEY)
        .header("Content-Type", "application/json")
        .header("X-Idempotency-Key", "upload-" + path + "-" + UUID.randomUUID())
        .POST(HttpRequest.BodyPublishers.ofString(bodyJson))
        .build();
    HttpResponse<String> res = HTTP.send(req, HttpResponse.BodyHandlers.ofString());
    JsonNode root = JSON.readTree(res.body());
    if (root.path("code").asInt() != 200) {
      throw new IOException(root.path("message").asText("API error"));
    }
    return root.get("data");
  }

  static String md5File(Path path) throws Exception {
    MessageDigest md5 = MessageDigest.getInstance("MD5");
    md5.update(Files.readAllBytes(path));
    StringBuilder sb = new StringBuilder();
    for (byte b : md5.digest()) {
      sb.append(String.format("%02x", b));
    }
    return sb.toString();
  }
}

Java 示例使用 Jackson（ObjectMapper）处理 JSON。请在项目中添加 com.fasterxml.jackson.core:jackson-databind，或改用你熟悉的 JSON 库解析响应。

分片上传

大文件流程：

POST .../multipart/initiate
POST .../multipart/presign-parts — presigned URL per part
PUT each part to CDN and record each part ETag
POST .../multipart/complete — finalize and get materialId
On failure: POST .../multipart/abort

分片大小请使用 initiate 响应中的 recommendedPartSize（S3 单片通常至少 5 MB，最后一片除外）。

示例

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);

import hashlib
import math
import os
import uuid

import requests

API_BASE = "https://api.vmeg.ai"
API_KEY = os.environ["VMEG_API_KEY"]
FILE_PATH = "./large.mp4"


def md5_file(path: str) -> str:
    h = hashlib.md5()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(1024 * 1024), b""):
            h.update(chunk)
    return h.hexdigest()


def idem_key(step: str) -> str:
    return f"multipart-{step}-{uuid.uuid4()}"


def api_post(path: str, body: dict) -> dict:
    res = requests.post(
        f"{API_BASE}{path}",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
            "X-Idempotency-Key": idem_key(path),
        },
        json=body,
        timeout=120,
    )
    res.raise_for_status()
    payload = res.json()
    if payload.get("code") != 200:
        raise RuntimeError(payload.get("message") or "API error")
    return payload["data"]


def upload_multipart() -> str:
    file_name = os.path.basename(FILE_PATH)
    file_hash = md5_file(FILE_PATH)
    file_size = os.path.getsize(FILE_PATH)

    init = api_post(
        "/openapi/v1/assets/material/upload/multipart/initiate",
        {"fileHash": file_hash, "fileName": file_name},
    )

    part_size = init.get("recommendedPartSize") or 8 * 1024 * 1024
    part_count = max(1, math.ceil(file_size / part_size))
    part_numbers = list(range(1, part_count + 1))

    presign = api_post(
        "/openapi/v1/assets/material/upload/multipart/presign-parts",
        {
            "materialId": init["materialId"],
            "uploadId": init["uploadId"],
            "fileHash": file_hash,
            "fileName": file_name,
            "partNumbers": part_numbers,
        },
    )

    parts = []
    with open(FILE_PATH, "rb") as f:
        for item in presign["urls"]:
            part_number = item["partNumber"]
            f.seek((part_number - 1) * part_size)
            chunk = f.read(part_size)
            put = requests.put(item["url"], data=chunk, timeout=600)
            put.raise_for_status()
            e_tag = put.headers.get("ETag", "").strip('"')
            parts.append({"partNumber": part_number, "eTag": e_tag})

    material = api_post(
        "/openapi/v1/assets/material/upload/multipart/complete",
        {
            "materialId": init["materialId"],
            "uploadId": init["uploadId"],
            "fileHash": file_hash,
            "fileName": file_name,
            "parts": parts,
        },
    )
    material_id = material["materialId"]
    print("materialId:", material_id)
    return material_id


if __name__ == "__main__":
    upload_multipart()

import java.io.IOException;
import java.io.RandomAccessFile;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;
import java.security.MessageDigest;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.UUID;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;

public final class MultipartMaterialUpload {
  private static final String API_BASE = "https://api.vmeg.ai";
  private static final String API_KEY = System.getenv("VMEG_API_KEY");
  private static final Path FILE_PATH = Path.of("large.mp4");

  private static final HttpClient HTTP = HttpClient.newBuilder()
      .connectTimeout(Duration.ofSeconds(30))
      .build();
  private static final ObjectMapper JSON = new ObjectMapper();

  public static void main(String[] args) throws Exception {
    System.out.println("materialId: " + uploadMultipart());
  }

  static String uploadMultipart() throws Exception {
    String fileName = FILE_PATH.getFileName().toString();
    String fileHash = md5File(FILE_PATH);
    long fileSize = java.nio.file.Files.size(FILE_PATH);

    JsonNode init = apiPost(
        "/openapi/v1/assets/material/upload/multipart/initiate",
        Map.of("fileHash", fileHash, "fileName", fileName));

    long partSize = init.has("recommendedPartSize")
        ? init.get("recommendedPartSize").asLong()
        : 8L * 1024 * 1024;
    int partCount = (int) Math.max(1, (fileSize + partSize - 1) / partSize);

    List<Integer> partNumbers = new ArrayList<>();
    for (int i = 1; i <= partCount; i++) {
      partNumbers.add(i);
    }

    ObjectNode presignBody = JSON.createObjectNode();
    presignBody.put("materialId", init.get("materialId").asText());
    presignBody.put("uploadId", init.get("uploadId").asText());
    presignBody.put("fileHash", fileHash);
    presignBody.put("fileName", fileName);
    ArrayNode nums = presignBody.putArray("partNumbers");
    partNumbers.forEach(nums::add);

    JsonNode presign = apiPost(
        "/openapi/v1/assets/material/upload/multipart/presign-parts", presignBody);

    ArrayNode completedParts = JSON.createArrayNode();
    try (RandomAccessFile raf = new RandomAccessFile(FILE_PATH.toFile(), "r")) {
      for (JsonNode item : presign.get("urls")) {
        int partNumber = item.get("partNumber").asInt();
        long offset = (long) (partNumber - 1) * partSize;
        int len = (int) Math.min(partSize, fileSize - offset);
        byte[] chunk = new byte[len];
        raf.seek(offset);
        raf.readFully(chunk);

        HttpRequest put = HttpRequest.newBuilder()
            .uri(URI.create(item.get("url").asText()))
            .PUT(HttpRequest.BodyPublishers.ofByteArray(chunk))
            .timeout(Duration.ofMinutes(10))
            .build();
        HttpResponse<String> putRes = HTTP.send(put, HttpResponse.BodyHandlers.ofString());
        if (putRes.statusCode() < 200 || putRes.statusCode() >= 300) {
          throw new IOException("Part PUT failed: " + putRes.statusCode());
        }
        String eTag = putRes.headers().firstValue("etag")
            .orElse("").replace("\"", "");

        ObjectNode part = JSON.createObjectNode();
        part.put("partNumber", partNumber);
        part.put("eTag", eTag);
        completedParts.add(part);
      }
    }

    ObjectNode completeBody = JSON.createObjectNode();
    completeBody.put("materialId", init.get("materialId").asText());
    completeBody.put("uploadId", init.get("uploadId").asText());
    completeBody.put("fileHash", fileHash);
    completeBody.put("fileName", fileName);
    completeBody.set("parts", completedParts);

    JsonNode material = apiPost(
        "/openapi/v1/assets/material/upload/multipart/complete", completeBody);

    return material.get("materialId").asText();
  }

  static JsonNode apiPost(String path, Object body) throws Exception {
    String bodyJson = body instanceof String ? (String) body : JSON.writeValueAsString(body);
    HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create(API_BASE + path))
        .timeout(Duration.ofSeconds(120))
        .header("Authorization", "Bearer " + API_KEY)
        .header("Content-Type", "application/json")
        .header("X-Idempotency-Key", "multipart-" + path + "-" + UUID.randomUUID())
        .POST(HttpRequest.BodyPublishers.ofString(bodyJson))
        .build();
    HttpResponse<String> res = HTTP.send(req, HttpResponse.BodyHandlers.ofString());
    JsonNode root = JSON.readTree(res.body());
    if (root.path("code").asInt() != 200) {
      throw new IOException(root.path("message").asText("API error"));
    }
    return root.get("data");
  }

  static JsonNode apiPost(String path, Map<String, String> body) throws Exception {
    return apiPost(path, (Object) JSON.valueToTree(body));
  }

  static String md5File(Path path) throws Exception {
    MessageDigest md5 = MessageDigest.getInstance("MD5");
    md5.update(java.nio.file.Files.readAllBytes(path));
    StringBuilder sb = new StringBuilder();
    for (byte b : md5.digest()) {
      sb.append(String.format("%02x", b));
    }
    return sb.toString();
  }
}

上传之后

仅在完整上传流程成功后，才能在音视频翻译的 source.materialId 中使用已注册的 materialId。管理资产见素材。

快速开始

鉴权

MCP

可靠请求

Webhooks

资产

产品

限制

选择上传方式

单文件上传

示例

分片上传

示例

上传之后

​选择上传方式

​单文件上传

​示例

​分片上传

​示例

​上传之后

选择上传方式

单文件上传

示例

分片上传

示例

上传之后