figure

Figure

Generate a figure from the prompt and surrounding context.

Input

• File path: the file being processed.
• Surrounding text: the paragraph or block where the <@figure ...> tag appears.
• Prompt (optional): description of the figure. If absent, infer from surrounding text.

Workflow

1. Read the surrounding text and prompt.
2. Synthesize a detailed image-generation prompt from user intention and context.
3. Generate the image using the API call below.
4. Save the image in the same directory as the source file. Name it based on the prompt (e.g., figure_system_architecture.png).
5. Replace the <@figure> tag with a format-appropriate image reference:
   • Markdown (.md): ![description](filename.png)
   • LaTeX (.tex): \includegraphics{filename.png}

API call

Requires GEMINI_API_KEY environment variable.

Run the entire generate-and-save flow in a single Bash command to avoid redundant API calls. Use single-quoted JSON with the prompt inserted via variable substitution to avoid escaping issues.

source ~/.bashrc && RESPONSE=$(curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "Generate an image: YOUR_PROMPT_HERE"}]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }') && echo "$RESPONSE" | python -c "
import json, sys, base64
r = json.load(sys.stdin)
if 'error' in r:
    print('API error: ' + r['error'].get('message', 'unknown')); sys.exit(1)
if 'candidates' not in r:
    print('No candidates in response'); sys.exit(1)
for part in r['candidates'][0]['content']['parts']:
    if 'inlineData' in part:
        data = base64.b64decode(part['inlineData']['data'])
        with open('OUTPUT_PATH.png', 'wb') as f:
            f.write(data)
        print(f'Saved {len(data)} bytes')
        break
"

Context References

The prompt may contain context references wrapped in double backticks ( ``). These point to external resources.

• As input: Read the referenced resource to inform the figure generation. E.g., <@figure: a diagram based on the architecture in ``system.md``> — read system.md for context.
• As output: If the prompt specifies an output path via a context reference, save the image there instead of auto-naming. E.g., <@figure: pipeline diagram, save to ``figures/pipeline.png``> — save to figures/pipeline.png.
• Resolve references relative to the source file's directory unless an absolute path is given.
• Remove the delimiters from the output.

Rules

• Run the API call and image save in a single Bash invocation. Do not split into separate calls.
• Keep the prompt in single-quoted JSON to avoid shell escaping issues. If the prompt contains single quotes, escape them.
• If GEMINI_API_KEY is not set, warn the user and skip.
• Use python (not python3) for base64 decoding.
• Sanitize the filename: lowercase, underscores, no spaces or special characters (unless an explicit output path is given via context reference).
• Resolve all context references ( ``) in the prompt before generating.