Slot Math & GDD

Gemini API and Veo notes for the VFX pipeline

Status: working research notes

Last verified against official Google documentation: 2026-08-18

These notes describe how the Gemini API should be used in the Magic Vault art and VFX pipeline. They do not define runtime game behaviour and are not a math source of truth.

1. API surface

The Gemini API currently exposes several different API families. They should not be treated as interchangeable:

  • CreateInteraction is Google's recommended general primitive for agentic, stateful and multimodal workflows.
  • generateContent is appropriate for a single complete multimodal response.
  • streamGenerateContent streams a response through SSE.
  • the Live API is a bidirectional WebSocket API for real-time interaction.
  • Gen Media APIs provide image and video generation through Gemini image models and Veo.
  • the Files API uploads larger inputs that should not be embedded as base64.

All REST requests use the x-goog-api-key header. Never place the API key in a browser bundle, prompt, generated artifact, committed file or CI log.

Official references:

2. Image generation

Use Gemini image generation for static concepts, isolated VFX endpoints, masks, guide maps and approved first/last frames.

Current model guidance from Google:

  • Gemini 3.1 Flash Image (Nano Banana 2) is the default general-purpose image model.
  • Gemini 3.1 Flash Lite Image is the lower-cost, lower-latency option.
  • Imagen is deprecated. Google documents a shutdown date of 2026-08-17, so no new pipeline may depend on Imagen.

For production assets, generation output is still only source material. Run background cleanup, alpha inspection, crop/pivot normalization and visual QA before runtime packaging.

3. Veo 3.1 input modes

The three image-related inputs have different semantics.

image

This is the initial image to animate. It is effectively the first scene/frame, not a style-only reference. If a character card is passed here, expect the character card to appear in the video.

Use it for:

  • animating an approved isolated flame, portal, rune or symbol;
  • rigid symbol idle motion;
  • a transition whose exact opening composition is important.

Do not use it when the source object must be absent from the generated video.

lastFrame

This constrains the final frame and must be used together with image. Use first/last frame interpolation when topology changes or when an exact endpoint matters.

For an exact loop, using the same canonical image as first and last frame can strongly constrain the endpoints, but it does not guarantee that the internal motion is loop-safe. Curate the motion and replace the extracted first and last runtime frames with the canonical PNG.

referenceImages

Veo 3.1 accepts up to three reference images. Google describes these as style and content references and demonstrates them as assets whose appearance should be preserved in the output. They are therefore not a reliable exclusion mechanism.

If H1 is supplied as a referenceImage, a negative prompt such as no character does not guarantee that H1, her silhouette, armour, frame or colour blocking will be absent.

For VFX that must not contain the character:

  1. analyze H1 with Gemini Vision;
  2. produce a text-only style specification;
  3. remove identity and physical-object descriptions from that specification;
  4. call Veo without H1 in image or referenceImages;
  5. optionally provide an abstract VFX guide map that contains no face, body, armour or frame.

4. Veo parameters relevant to this project

According to the current Veo 3.1 documentation:

  • aspect ratio: 16:9 or 9:16;
  • duration: 4, 6 or 8 seconds;
  • reference-image, extension and high-resolution cases require an 8-second duration;
  • resolution: 720p, 1080p or 4k for supported Veo 3.1 variants;
  • 1080p and 4k require 8 seconds;
  • extension is limited to 720p and to videos generated by Veo;
  • seed may improve repeatability slightly but does not guarantee deterministic output;
  • generation is asynchronous: submit an operation, poll that exact operation and download its result when complete.

Model availability and accepted combinations can differ between model variants and preview releases. A rejected validation request is not a successful generation and must not be counted as spend, but its error should be retained as compatibility evidence.

For Magic Vault, prefer separated effects rather than one prompt containing every requested phenomenon:

fire_and_smoke
ruby_light_pulses
armour_runes
inner_frame_fire
sparks_and_ash
plaque_runes
outer_aura

Generate each effect on exact black (#000000) with generous safe padding. Composite it in PixiJS using add or screen. Black-background RGB video does not require an alpha channel.

This separation provides:

  • independent placement and intensity control;
  • reusable effects across symbols;
  • fewer unwanted physical objects;
  • smaller correction scope when a generation fails;
  • easier conversion into curated RGBA frames or sprite atlases.

6. Reference-safe workflow

When the final render must not show the reference:

approved character reference
    -> Gemini visual analysis
    -> structured style JSON
    -> identity/object stripping
    -> VFX-only text prompt
    -> Veo text-to-video
    -> contact-sheet and edge QA
    -> black cleanup/runtime derivative
    -> PixiJS or Spine composition

A useful style JSON contains only properties such as:

{
  "rendering": "premium stylized fantasy mobile-slot VFX",
  "palette": ["orange", "ruby red", "polished gold"],
  "light": "soft volumetric glow with crisp luminous cores",
  "fire": "elegant tapered tongues with controlled embers",
  "smoke": "thin translucent upward curls",
  "materials": "not applicable; luminous phenomena only",
  "detail": "clean high-production rendering readable at symbol scale"
}

Do not carry character nouns, anatomy, clothing, card geometry, logos or readable text into the Veo prompt.

7. Guide maps and masks

If the effect must follow a character region, use an abstract guide map instead of the coloured character reference. A guide map may identify:

  • hair-tip fire zones;
  • armour-edge rune zones;
  • four ruby-light positions;
  • plaque-rune zone;
  • card safe area and particle exclusion area.

Avoid a complete Canny/line-art silhouette when the human shape must not appear. ControlNet can faithfully turn such a contour into a glowing person-shaped effect.

Masks and maps are spatial constraints, not runtime art. Do not export them into the final game asset pack unless the runtime effect explicitly consumes them.

8. Prompt rules for isolated VFX

Positive prompts should state:

  • a single clear effect;
  • how it moves, using verbs such as flickers, rises, travels, pulses and fades;
  • pure black background;
  • locked camera;
  • centered composition and safe padding;
  • intended loop behaviour;
  • absence of physical objects.

Negative prompts should explicitly exclude:

character, person, face, body, hair mass, armour, card, frame, gemstone,
plaque, logo, readable text, UI, environment, camera motion, edge contact

Negative prompting is not a hard mask. If an excluded object appears, reject the generation or change the conditioning input rather than treating the prompt as a guarantee.

9. QA and cost gate

Before every paid generation, record and obtain approval for:

  • model and variant;
  • input mode: text, image, first/last frame or referenceImages;
  • resolution, aspect ratio and duration;
  • number of requested videos;
  • maximum cost.

After generation:

  1. retain the raw response and operation identity;
  2. inspect a contact sheet and motion preview;
  3. verify that no protected reference object leaked into the video;
  4. verify locked camera, stable scale and black edges;
  5. reject clips whose particles touch or leave the canvas;
  6. keep rejected clips as negative evidence, not approved runtime assets;
  7. create a separate cleaned runtime derivative instead of overwriting the raw video.

10. Decision after the H1 silhouette-fire tests

The safest generic path remains text-only style extraction: do not submit H1 as image or referenceImage when the effect must contain no recognizable character content. Use H1 only for Gemini visual analysis, then generate the following layers independently:

  1. hair-tip fire and smoke;
  2. ruby-red corner pulses;
  3. golden rune traces;
  4. sparks and ash;
  5. optional inner fire contour and outer aura.

Assemble the accepted layers around the approved character and frame in the runtime engine.

A controlled hybrid test also succeeded at excluding the visible character:

neutral outline guide + H1 referenceImages style anchor + explicit object exclusions

The result contained only perimeter fire and kept the silhouette interior empty, but it also invented an upper-left 00000 artifact and failed to produce a native seamless loop. Therefore the hybrid path is permitted for experiments where following the H1 contour matters, but it is not a guarantee and is not the preferred route for generic reusable VFX. Its evidence and runtime derivative are stored at output/veo-video-tests/2026-08-18-h1-silhouette-fire-wrap-01/.