civiltekk-zai-media-skill
Z.AI media production, four routes. image: generate images from text prompts via the GLM-Image API (/images/generations), saved as local PNGs. video: generate video from a text or first-frame-image pr
SKILL.mdskills/civiltekk-zai-media-skill/SKILL.md
GitHubConsolidates zai-image-generation-skill + zai-video-skill + zai-asr-skill + zai-ocr-skill (#604). Alias: formerly those four skills.
What I do
Z.AI media generation and extraction across four routes. Every route is a bash recipe against a direct Z.AI HTTP endpoint — OpenCode's provider layer is chat-only, so none of these endpoints is reachable through a provider:
- Detect the route (§Routes) — explicit > inferred > ask-once.
Explicit: the request names the activity ("generate image", "draw a
picture", "text to image" →
image; "generate video", "text to video", "image to video" →video; "transcribe", "speech to text", "ASR" →transcribe; "OCR", "extract text from image", "layout parsing" →ocr). Inferred: the artifact shape (a picture from a prompt →image; an MP4 from a prompt or first-frame image →video; a transcript from an audio file →transcribe; text/layout from an image or PDF →ocr). Ambiguous ("make media for this README") → ask once per run, then proceed on the answer. - Load the route's values file (§Side files) and run its recipe verbatim — do not improvise endpoints, models, or parameters.
- Run the shared lifecycle (§Lifecycle) around that recipe: key resolution → endpoint call → parse → persist → return.
Lifecycle (shared method — every route)
| Step | Rule |
|---|---|
| 1. Key resolution | $ZAI_API_KEY env first, then the OpenCode credential-store fallback — the exact jq snippet lives per route in the values files and stays verbatim: key order differs by route (image prefers the coding-plan key; the pay-as-you-go routes prefer the zai key). If neither source has the key, stop and report — do not proceed. |
| 2. Endpoint call | Endpoint policy is per route and must not be unified: image defaults to the coding-plan endpoint via ZAI_IMAGE_ENDPOINT (plus its compliance note); video/transcribe/ocr target pay-as-you-go https://api.z.ai/api/paas/v4 via ZAI_MEDIA_ENDPOINT. Exact defaults live in the values files. |
| 3. Parse | python3 JSON parse of the response; an "error" key → print the error body and stop (do not retry-loop). |
| 4. Persist | image/video: the API returns a temporary URL — download to a local file and verify with file(1) before claiming success. transcribe: transcript text on the TRANSCRIPT: line. ocr: extracted content on stdout. |
| 5. Return | Path contract (§Return Contract) — the SAVED: / TRANSCRIPT: / stdout result, never the API response JSON or temporary URLs. |
Harness binding for step 1 (§Portability contract): the ZAI_API_KEY env
var is the portable credential row — it alone works on every harness. The
~/.local/share/opencode/auth.json fallback reads OpenCode's credential
store (bonus row; ignore elsewhere — export the env var). Other/none (no
auth.json store): export ZAI_API_KEY — the env var alone is sufficient.
Recipe execution needs bash + curl + jq (any harness with a shell tool).
Requires bash (git-bash/WSL on Windows).
Background shells (video poll loop)
Video generation takes minutes — the poll loop must not block the session as a foreground command. Harness binding (§Portability contract):
- OpenCode — shell
background: true: the call returns immediately and you are notified when the command exits — continue other work and read the result then. - Claude Code — Bash
run_in_background: true. - Other/none — run the same loop in the foreground and tell the caller it blocks the session (correct, just slower).
Requires bash (git-bash/WSL on Windows).
Side files (load rules)
| Read | When | Use |
|---|---|---|
references/image.md |
route image |
GLM-Image recipe: coding-plan endpoint default + ZAI_IMAGE_ENDPOINT override, SIZE/QUALITY/MODEL options, mfile.z.ai reachability note, compliance note (separate PAYG product; risk-control on the coding endpoint) |
references/video.md |
route video |
CogVideoX-3 recipe: PAYG only (ZAI_MEDIA_ENDPOINT), submit → background poll → download/verify, ~$0.20/video cost note |
references/asr.md |
route transcribe |
GLM-ASR recipe: PAYG only (ZAI_MEDIA_ENDPOINT), ≤25 MB / ≤30 s / wav-mp3 hard limits, ffmpeg split/convert |
references/ocr.md |
route ocr |
GLM-OCR recipe: PAYG only (ZAI_MEDIA_ENDPOINT), Path A public-URL layout_parsing, Path B local-file vision fallback (ponytail note on the base64 rejection) |
Side files carry VALUES only; this file carries the METHOD plus the lifecycle and background-shell bindings above.
Routes
| Situation | Route |
|---|---|
| "image generation", "generate image", "text to image", "draw a picture"; a picture artifact from a text prompt | image |
| "video generation", "generate video", "text to video", "image to video"; an MP4 artifact from a prompt or first-frame image | video |
"transcribe", "speech to text", "ASR", "audio transcription"; a transcript from a .wav/.mp3 file |
transcribe |
| "OCR", "extract text from image", "layout parsing", "document text extraction"; text/layout from an image or PDF | ocr |
| Ambiguous | ask once (§What I do step 1), then route |
| Sync vs async | image, transcribe, ocr — one synchronous call. video — minutes-long async: submit, then poll loop as a background shell (§Background shells). |
Boundaries
- Analyzing or describing an existing image or video (not producing one)
is perception work, not this skill — use native vision
(
image-analyzer-subagent); this skill only produces artifacts. - Z.AI chat/vision-provider work outside these four endpoints (web search, chat completions) is the provider layer's space, not this skill's.
- Audio longer than 30 s: split first (ffmpeg segment), then transcribe
the segments in order and concatenate — see
references/asr.md. zai-media-subagentis the agent that runs this skill by route (delegated media production keeps payloads and key usage out of the primary context).
Agent behavior rules
- Announce billable cost before submitting.
video/transcribe/ocrare pay-as-you-go and not covered by the GLM Coding Plan; async video tasks are billable once they run — submit only after the caller confirmed intent. - Stop on missing key — never fabricate an artifact or transcript;
report
Status: failed("ZAI_API_KEY not set"). - Verify before success — a route is successful only after the file
exists on disk and
file(1)reports the expected type (image,video), or the text actually parsed (transcribe,ocr). - Headless/CI: no asks — read the route from the delegation prompt and use its documented default behavior.
Return Contract
**Status:** [success | partial | failed]
**Output:** [artifact path / transcript / extracted text — one line]
**Summary:** route `{route}` — [2–3 sentences max]
**Issues:** [blockers, incl. missing key / API error / unreachable download host, or "None"]