Z AI Multifunction Workflow (Chat, Agent, Video, File Upload)
A single, secure tool endpoint that intelligently routes requests to four Z.ai capabilities:
- Z Chat API with GLM‑4.5 family (text generation, reasoning, tools)
- Z Agent Chat (e.g., general_translation agent)
- Z Video Generation (CogVideoX‑3 and Vidu series)
- Z Agent File Upload (PDF, DOC, XLSX, PPT, TXT, JPG, PNG)
This README explains what the workflow does, how routing works, supported inputs, defaults, and how to call it with examples. Where helpful, it draws on guidance from:
⚙️ Workflow Logic
The gateway operates on a clear and prioritized logic flow to handle your requests efficiently.
- Tool Trigger: The workflow is initiated by an API call to the Tool Trigger endpoint.
- Initial Router: A simple script checks if an
agentId is provided. This helps distinguish between a general chat request and a request for a specific AI agent.
- Priority Switch: The request is then evaluated by a switch with the following priority order (
first_match):
- Is it a Video request? (
createVideo is true)
- ➡️ Route to Video Creation & Fetch Result nodes.
- Is it a File Upload request? (
uploadFile is true)
- ➡️ Route to Agent File Upload node.
- Is it for a specific Agent? (
agentId is provided)
- ➡️ Route to Agent Chat node.
- Otherwise, it's a standard Chat request.
- ➡️ Route to Chat API node.
- Flow Output: The result from the executed branch is returned as the final API response.
This design ensures that more specific tasks (like video creation) are handled first, with general chat as the default fallback.
Why use this workflow?
- One endpoint for text, agents, video, and file uploads
- Clean request shape; the workflow builds the right payload for each Z.ai API
- Safe-by-default validation (file size/format checks, language defaults, etc.)
- Good defaults for production (GLM‑4.5 chat, 1080p video, 30fps, 5s duration)
Capabilities at a glance
- Chat (Z Chat API, GLM‑4.5 family)
- System/user/assistant messages, conversation history supported in node (this version routes minimal inputs)
- Advanced controls in node: temperature, top_p, max_tokens, tools, response_format, thinking, stop, do_sample
- Defaults set for a helpful general assistant
- Agent Chat (Z Agents API)
- Supports agent_id (e.g., general_translation)
- Structured messages with roles and content
- Optional stream, custom_variables, acceptLanguage supported in node (this version routes minimal inputs)
- Video Generation (Z Video API)
- Models: cogvideox-3 (premium), viduq1-* (1080p anime/stylized), vidu2-* (budget, 480p)
- Text-to-video, image-to-video, start-end transitions, multi-reference
- Node supports quality, audio, size, fps, style, duration, aspect ratio, movement amplitude (this version uses sensible defaults)
- Agent File Upload (Z Agent Files API)
- Base64 or external URL input
- Validates up to 100MB and supported formats (pdf, doc, xlsx, ppt, txt, jpg, png)
- Returns file object with id, filename, size, etc.
Routing logic
The endpoint chooses a path based on your request:
Condition (in request body)Route takencreateVideo === trueVideo Creation → Fetch ResultElse if uploadFile === trueAgent File UploadElse if agentId is providedAgent ChatElseChat (GLM‑4.5)
Note: A tiny “Route Request” script also resolves “chat” vs “agent” based on agentId.
Security
This workflow uses two keys:
- Tool endpoint key (required as an HTTP header)
- Header: buildship_api_key: YOUR_TOOL_KEY
- Configure/view in your Buildship Tool Trigger settings
- Z AI API key (sent in the request body, forwarded to Z.ai services)
If the header key is invalid, the endpoint returns 401.
Endpoint
- Method and URL are provided by Buildship when you deploy this Tool Trigger (copy from your environment).
- Request content type: application/json
- Body size limit: 1MB on free plan, 32MB on paid (internal parser limit)
Common request fields (body)
- apiKey: string (required) — your Z AI API key (zsk_…)
- prompt: string (required) — your text prompt or question; also used as userMessage for agents
- model: string (required) — used for Video only in this version; Chat always uses GLM‑4.5
- createVideo: boolean — route to video generation when true
- uploadFile: boolean — route to file upload when true
- filename: string — required for file upload
- fileBase64: object — for file upload
- type: "base64" | "external-url"
- file: string — a data URL/base64 string or an external URL
- agentId: string — route to Z Agent Chat when provided (e.g., "general_translation")
Defaults (if not set via request):
- Accept-Language: en-US,en (affects API system responses/errors, not translation output)
- Chat model: GLM‑4.5 (hard-coded in this version)
- Video (when createVideo = true): cogvideox-3, 1920x1080, 30fps, 5s, realistic, movement=auto, with_audio=false, quality=quality
Quickstart examples
Replace:
- {TOOL_ENDPOINT} with your deployed endpoint
- {TOOL_HEADER_KEY} with your Buildship tool key
- zsk_xxx with your Z AI API key
1) Chat (GLM‑4.5)
Note: The top-level “model” you send is ignored for chat in this version; GLM‑4.5 is used.
curl -X POST {TOOL_ENDPOINT} -H "Content-Type: application/json" -H "buildship_api_key: {TOOL_HEADER_KEY}" -d '{ "apiKey": "zsk_xxx", "prompt": "Write a friendly 3-sentence product update about faster checkout.", "model": "glm-4-5" }'
What you get back (shape from Z Chat API):
- choices[0].message.content: string (model’s answer)
- usage: prompt/completion/total tokens
- model, id, created, request_id
2) Agent Chat (General Translation)
Agent IDs are defined by Z.ai. This flow sends your prompt as the user message to the specified agent.
curl -X POST {TOOL_ENDPOINT} -H "Content-Type: application/json" -H "buildship_api_key: {TOOL_HEADER_KEY}" -d '{ "apiKey": "zsk_xxx", "agentId": "general_translation", "prompt": "Translate to French: Hello, how are you today?" }'
What you get back (shape from Z Agents API):
- choices[0].object.messages: array of structured messages
- status, id, agent_id
- usage: prompt_tokens, completion_tokens, total_tokens, total_calls
Tip: This version routes minimal inputs. For advanced options like custom_variables (e.g., source_language, target_language, glossary), extend the node to accept them from the public inputs.
3) Video Generation (CogVideoX‑3 by default)
This version exposes prompt and model; other options use defaults (1080p, 30fps, 5s, no audio, movement=auto, quality=quality).
curl -X POST {TOOL_ENDPOINT} -H "Content-Type: application/json" -H "buildship_api_key: {TOOL_HEADER_KEY}" -d '{ "apiKey": "zsk_xxx", "createVideo": true, "model": "cogvideox-3", "prompt": "A cinematic slow-motion shot of ocean waves at sunset with golden light." }'
What you get back:
- The node first creates the task, then immediately fetches async status once.
- Response fields: task_status (e.g., PROCESSING or SUCCEEDED), model, request_id, and when complete video_result[{ url, cover_image_url }].
Note: If still processing, poll the async-result endpoint yourself or enhance the workflow with a polling loop/backoff.
Supported models in the node:
- cogvideox-3 — premium quality, up to 4K, 30/60 fps, audio supported
- viduq1-text — text-to-video, anime style, 1080p, 5s
- viduq1-image — single image to video, 1080p, 5s
- viduq1-start-end — start/end frame transition, 1080p, 5s
- vidu2-image — budget image-to-video, 480p, 4s
- vidu2-start-end — budget start/end, 480p, 4s
- vidu2-reference — multi-reference with audio, 480p, 4s
4) Agent File Upload
Provide base64 or external URL; include filename (with extension).
curl -X POST {TOOL_ENDPOINT} -H "Content-Type: application/json" -H "buildship_api_key: {TOOL_HEADER_KEY}" -d '{ "apiKey": "zsk_xxx", "uploadFile": true, "filename": "document.pdf", "fileBase64": { "type": "external-url", "file": "https://example.com/docs/product-brief.pdf" } }'
What you get back:
- File object: { id, object, bytes, filename, created_at, purpose }
Validation the node enforces:
- Size ≤ 100MB
- Extensions: pdf, doc, xlsx, ppt, txt, jpg, png
- For base64, strips data URL prefix and builds File
- For external URLs, fetches the file and creates File
GLM‑4.5 highlights (Chat)
Based on the GLM‑4.5 API usage in this flow (see docs for details):
- Models: glm-4.5 (flagship), glm-4.5-air, glm-4.5-x, glm-4.5-airx, glm-4.5-flash, glm-4-32b-0414-128k
- Controls available in the node:
- temperature (0.0–1.0; default 0.6)
- top_p (0.0–1.0; default 0.95)
- max_tokens (e.g., up to 96k for GLM‑4.5; 16k for GLM‑4‑32B)
- stream (SSE)
- stop (stop sequences)
- tools (function calling)
- response_format (text or json_object)
- thinking (enable chain-of-thought for GLM‑4.5+)
- do_sample (default true)
- user_id, request_id (tracing)
- Messages format used in node: [{ role, content }]
Current workflow behavior:
- Uses GLM‑4.5 for Chat branch (ignores top-level model input)
- Sends minimal messages: optional system/assistant/history are present in node, but public endpoint provides user prompt only in this version
- Accept-Language defaults to en-US,en
To expose more GLM controls publicly, map the input fields to the Chat node’s inputs (temperature/top_p/etc.).
Docs: https://docs.z.ai/guides/llm/glm-4.5
CogVideoX‑3 highlights (Video)
Key points aligned with CogVideoX‑3 guide and this node:
- Quality: Professional-grade, realistic physics, high subject clarity/stability
- Resolution: up to 4K (3840×2160) on CogVideoX‑3; node default: 1920×1080
- FPS: 30 or 60 for CogVideoX‑3 (default 30 here)
- Audio: supported on CogVideoX‑3 (default disabled here)
- Duration: variable for CogVideoX‑3; node default is 5s
- Movement Amplitude: auto, subtle, moderate, strong (default auto)
- Quality Mode: quality vs speed (default quality)
Best practices for prompts:
- Be specific about subjects, actions, environment, lighting, camera, and style
- 50–300 characters often works well
- For anime style (viduq1-text), include anime-specific cues
- For image-to-video/start-end/reference models, provide clear URLs and desired motion
Docs: https://docs.z.ai/guides/video/cogvideox-3
Typical use cases
- Unified AI backends: text, translation agents, videos, and file ingestion via one endpoint
- Product marketing: generate announcements with GLM‑4.5; create a short product clip with CogVideoX‑3
- Localization workflows: call general_translation; optionally upload product PDFs for reference
- Content production: prototyping videos in speed mode, final cut in quality mode (extend node inputs if needed)
Output shapes (high-level)
- Chat (Z Chat API)
- { id, created, model, choices: [{ message: { role, content }, finish_reason, index }], usage: { prompt_tokens, completion_tokens, total_tokens }, request_id }
- Agent Chat (Z Agents API)
- { id, status, agent_id, choices: [{ object: { messages: [ ... ], finish_reason, index } }], usage: { prompt_tokens, completion_tokens, total_tokens, total_calls } }
- Video (Fetch async result)
- { model, request_id, task_status, video_result: [{ url, cover_image_url }] }
- File Upload (Z Agent Files API)
- { id, object: "file", bytes, filename, created_at, purpose }
Errors:
- Tool header missing/invalid: 401 "Invalid API key"
- Z.ai API errors are bubbled with status and body
- File node throws readable validation errors (size/format/fetch failures)
Known limitations in this version
- Chat branch always uses GLM‑4.5 (top-level “model” input is ignored for chat)
- Agent Chat exposes only agentId + prompt publicly (no custom_variables/stream in request)
- Video branch exposes only model + prompt publicly (fps/size/duration/movement/etc. are node defaults)
- Video result is fetched once; add a polling loop if you need to wait until completion
- Accept-Language is fixed to en-US,en (exposed in nodes, but not as public input)
You can easily extend the workflow:
- Expose additional inputs at the top level (Tool Trigger → Switch path node → map fields)
- Add a wait-and-retry loop for video async results
- Pass custom_variables to Agent Chat
Troubleshooting
- 401 Invalid API key
- Ensure you set buildship_api_key header to your tool’s key
- 4xx/5xx from Z.ai
- Verify your Z AI apiKey (zsk_…), quotas, and parameter validity
- File upload failures
- Check filename extension and ≤ 100MB
- For external URLs, ensure it’s publicly reachable and returns a valid image/doc
- Video still processing
- Poll the async-result endpoint until task_status is SUCCEEDED
Changelog (functional highlights)
- Secure Tool Trigger with header validation and body size limits
- Smart Switch routing across Video, File Upload, Agent Chat, and Chat
- Input validation for files and robust error handling
- Sensible defaults for GLM‑4.5 and CogVideoX‑3
References
By Stuart Gardoll
By BuildShip
