@apicity/machgen

MachGen video generation API provider.

Image generation uses the same api.v0.generate method: set task_type to T2I or I2I and supply image_config with height and optional width/aspect_ratio. The frontier image IDs are GPT-Image-2, GPT-Image-2.5-Sunburst, GPT-Image-2.5-Flare, Nano-Banana-2 and Nano-Banana-2.1. Edits take public HTTP(S) src_image_urls, up to 16 on the GPT Image models and 14 on the Nano Banana models (MACHGEN_I2I_MAX_IMAGES), or previous image src_task_ids. Poll api.v0.tasks for task_output.image. GPT Image 2 defaults to high quality; optimization_level: "EXPRESS" selects low quality. The recorded 1280×544 EXPRESS request billed $0.001385 before Generation Credit. Send Alibaba-Wan-3.0 requests with MachGen's documented video_config: aspect_ratio: "adaptive", fps: 30 and audio: true. On 2026-10-22, seven Wan 3.0 tasks that omitted aspect_ratio and fps and sent audio: false were accepted, then failed upstream with Request Rejected at zero charge. With the documented config, 2-second 480p T2V, I2V and R2V requests completed. Which of the three fields MachGen requires has not been isolated.

Runtime dependencies:

• zod@^4.6.6 — request schemas attached to every POST endpoint as .schema

Installation

npm install @apicity/machgen
# or
pnpm add @apicity/machgen

Quick Start

import { createMachGen } from "@apicity/machgen";

const machgen = createMachGen({ apiKey: process.env.MACHGEN_API_KEY! });

Video models

Pass a model id with a task_type it supports. For the ids below, machgen.api.v0.generate.schema also checks the height, duration_secs and aspect_ratio against the model's grid (MACHGEN_VIDEO_GRIDS, which holds each T2V and R2V grid too), the I2V frame rules, the R2V reference limits, the UPSCALE targets (MACHGEN_VIDEO_UPSCALE) and the SHARPEN heights (MACHGEN_VIDEO_SHARPEN); other ids pass unchecked. MachGen answers an off-grid request with HTTP 400 before it accepts the task, and does not bill it. The grids were read from those 400 responses on 2026-10-25, MiniMax-H3-Omni's on 2026-11-01, and the SHARPEN heights on 2026-10-31. -1 asks the model for a Smart length.

An I2V request takes one start frame in src_image_urls. Where the table lists "start + end", entry 1 is the end frame; "end only" means keyframe_indices: [-1] animates toward a single image used as the end frame. MachGen also accepts task_type: "F2F" for two-image I2V; the schema keeps the documented I2V form. MiniMax-H3 and MiniMax-H3-Turbo list 1080p, but MachGen answers 403 to accounts without access to it, and the pricebook has no 1080p rate. The pricebook's LTX-2.3-Pro 540p and 720p tiers are not requestable.

Reference-to-video

An R2V request takes reference images, videos and audio clips in src_image_urls, src_video_urls (public http(s) URLs) and src_audio_urls, or earlier outputs in src_task_ids. reference_video_start_secs lists one start second per reference video. reference_video_operation edits or extends the video instead of using it as a reference; an edit renders at the video's own length, so MachGen ignores duration_secs. MiniMax-H3-Omni is missing from MachGen's models table, but its model page and pricebook list it, and it takes R2V only. Beyond the caps below, every video task takes at most 9 images in src_image_urls, the limit MachGen documents for references, and at most 3 each in src_video_urls and src_audio_urls.

Upscale and sharpen

An UPSCALE task re-renders a finished video, named in src_task_ids or src_video_urls, at the target video_config.height; set duration_secs to the source's length. MiniMax-H3 upscales only its own 768p outputs of 5 s or more. MachGen also rejects a target at or below the source's height, and a gaia-2 target above twice it; those depend on the source, so the schema cannot check them.

A SHARPEN task sharpens one owned video and keeps its length: a MachGen output named in src_task_ids, or an upload referenced as @input/<artifact_path> in src_video_urls. MachGen refuses a public URL. It takes duration_secs, not num_frames. MachGen's quote prices the source's height and seconds, whatever the request's height or duration_secs, so set video_config.height to the source's height.

Priced lists the task types computeEstimate from @apicity/cost prices per output second. An R2V reference video also bills the seconds MachGen reads from it, after any start offset, so pass their total as costHints.inputDurationSeconds; an edit's output is that long too. An upscale bills by its source's length, so it needs the same hint; MiniMax-H3 bills those seconds in and out. A sharpen needs the hint too and bills the seconds once. Topaz bills vendor credits that depend on the source's frames and resolution, so computeEstimate does not price it; api.v0.upscale.quote asks MachGen for the exact price, and resolveMachGenUpscaleEstimate turns that quote into an estimate. Kling-v3, Kling-o3 and the Pixverse models price audio on and off apart, so set video_config.audio. api.v0.tasks.billing returns a finished task's actual charge in micro-USD.

import { createMachGen } from "@apicity/machgen";

const machgen = createMachGen({ apiKey: process.env.MACHGEN_API_KEY! });

const task = await machgen.api.v0.generate({
  model: "MiniMax-H3-Turbo",
  task_type: "I2V",
  prompt: "The cat slowly blinks and turns its head toward the window.",
  video_config: { height: 480, duration_secs: 4 },
  src_image_urls: [
    "https://example.com/start.jpg",
    "https://example.com/end.jpg",
  ],
});

let status = await machgen.api.v0.tasks(task.task_id);
while (status.status === "PENDING" || status.status === "RUNNING") {
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  status = await machgen.api.v0.tasks(task.task_id);
}
const bill = await machgen.api.v0.tasks.billing(task.task_id);
console.log(bill.generation_cost_micros / 1e6); // 0.06

API Reference

5 endpoints across 4 groups. Each method mirrors an upstream URL path.

assets

const res = await machgen.api.v0.assets({ /* ... */ });

generate

const res = await machgen.api.v0.generate({ /* ... */ });

tasks

const res = await machgen.api.v0.tasks({ /* ... */ });

const res = await machgen.api.v0.tasks.billing({ /* ... */ });

upscale

const res = await machgen.api.v0.upscale.quote({ /* ... */ });

Part of the apicity monorepo.

License

MIT — see LICENSE.