Grok Imagine Video

aimock mocks xAI's native Grok Imagine async video-generation API — submit a job under POST /v1/videos/generations, then poll it through pending → done | failed | expired under GET /v1/videos/{request_id}. It draws from the same endpoint: "video" fixture pool as the other video surfaces, disambiguated by the grok-imagine-* model string.

Endpoints

Sora-safe dispatch

Grok's status route, GET /v1/videos/{request_id}, shares its path shape with the OpenAI-shaped Sora /v1/videos/{id} surface. aimock resolves this with a job-map-first lookup: a GET that matches a live Grok job is served by the Grok handler, and any miss falls through to the unchanged Sora handleVideoStatus byte-for-byte (the two id namespaces are disjoint — Sora ids come from its own state map, Grok request ids are minted UUIDs). The literal /v1/videos/generations submit path is guarded so it is never parsed as a status id of "generations". Existing Sora behavior is unaffected.

Fixture Authoring

Submits are matched against endpoint: "video" fixtures on the request's prompt (via match.userMessage, read from body.prompt) and model (via match.model, default grok-imagine-video). The grok-imagine-* model string is the provider disambiguator — Grok, Veo, and OpenRouter video fixtures share one match namespace, and their model tokens never overlap.

mock.onVideo("a cat playing piano", {
  // `id` is required by the type but ignored on this surface (the request_id
  // is always server-minted); `url` is served as-is, no byte proxying.
  video: { id: "vid_1", status: "completed", url: "https://videos.x.ai/abc.mp4", duration: 6, cost: 0.12 },
}, { model: "grok-imagine-video" });

// A failed job:
mock.onVideo("impossible prompt", {
  video: { id: "vid_2", status: "failed", error: "content policy violation" },
}, { model: "grok-imagine-video" });

The fixture's video object supports:

• status — "completed" or "failed" sets the job's terminal state. The wire status is derived from the stored value: a stored "completed" serializes to the wire "done"; the stored status is always "completed", never the wire "done".
• id — ignored on this surface (the request_id is always a server-minted UUID)
• url? — the video URL surfaced as video.url on a done poll, served as-is (no byte proxying)
• duration? — clip duration surfaced as video.duration (defaults to 0)
• cost? — generation cost in USD, surfaced as usage.cost_in_usd_ticks on completion (see units below)
• error? — failure message surfaced as { code, error } on a failed poll

Progress & Polling Realism

Grok reports a progress percentage on every poll; aimock synthesizes it from the poll count (climbing toward 100, reaching 100 when the job is done). By default a submitted job is seeded terminal internally. To exercise client code that polls through intermediate states, pass grokVideo with poll thresholds. The semantics are identical to falQueue and the OpenRouter video surface.

const mock = new LLMock({
  port: 0,
  grokVideo: { pollsBeforeInProgress: 1, pollsBeforeCompleted: 2 },
});

// Submit  → { request_id }
// poll 1  → { request_id, status: "pending", progress: … }
// poll 2  → { request_id, status: "done", progress: 100, video: { url, duration }, usage: { cost_in_usd_ticks } }

Thresholds are sanitized exactly as on the other video surfaces (non-finite treated as unset; negatives/fractions floored and clamped). createServer warns at startup on invalid values.

JSON-only — multipart rejected

Cost units

Grok bills in cost_in_usd_ticks, an integer count of USD ticks where 1 USD = 1e10 ticks. A fixture's video.cost is the cost in USD; on a done poll aimock surfaces usage.cost_in_usd_ticks = round(cost × 1e10). Record mode persists the upstream cost back to USD (cost = cost_in_usd_ticks / 1e10) so it round-trips.

Chaos & Metrics

Chaos injection applies to both routes. In Prometheus metrics the per-job status path is templated as /v1/videos/{request_id} to keep label cardinality bounded.

Record Mode

With record mode and the grok provider configured, an unmatched submit becomes a live interactive proxy: the /v1/videos/generations POST is forwarded to the real API and answered with a mock-rewritten { request_id } envelope (a fresh aimock request id), and each client poll is proxied upstream 1:1 with the mock request id substituted. The client's own polling drives the upstream lifecycle.

{
  "llm": {
    "fixtures": "./fixtures",
    "record": {
      "providers": { "grok": "https://api.x.ai" }
    }
  }
}

const mock = new LLMock({
  record: {
    providers: { grok: "https://api.x.ai" },
  },
});

When the upstream poll reports done, the completed poll body is relayed first and the eager capture then runs synchronously on the request stack (there is no byte download to detach): aimock reads the video URL, duration, and cost straight out of the terminal poll body (no download — the URL is served as-is) and persists a normal video fixture (match.userMessage = the prompt, match.model = the submitted model under the standard model-normalization rules, video.id = the upstream request id, video.status = "completed", video.url / video.duration, plus cost converted from cost_in_usd_ticks). The same submit then replays in-session and across sessions. Relayed poll bodies are otherwise faithful: status, progress, video.url, and usage pass through verbatim with only the request id rewritten. A failed upstream persists a failed fixture ({ status: "failed", error }) and relays { request_id, status, progress, code, error }; expired (and any terminal status not representable in video.status) passes through with a warning, persists nothing, and keeps proxying.

The polling client's Bearer credential is forwarded only to the configured provider origin: the submit response carries just a request_id (never an upstream poll URL), so there is nothing off-origin to adopt or validate — the poll URL is always constructed on the configured provider origin from that request id. Strict mode wins over record: a strict no-match returns 503 and nothing is proxied. Without a configured grok provider URL, --record warns and serves the normal no-match 404. Under proxy-only mode (record.proxyOnly / --proxy-only) nothing is persisted and a done job is never converted to a local replay job — every poll keeps proxying upstream.