Zhipu AI Agents API
The Agents API from Zhipu AI — 3 operation(s) for agents.
OpenAPI Specification
openapi: 3.0.1
info:
title: Z.AI Agents API
description: Z.AI API available endpoints
license:
name: Z.AI Developer Agreement and Policy
url: https://chat.z.ai/legal-agreement/terms-of-service
version: 1.0.0
contact:
name: Z.AI Developers
url: https://chat.z.ai/legal-agreement/privacy-policy
email: user_feedback@z.ai
servers:
- url: https://api.z.ai/api
description: Production server
security:
- bearerAuth: []
tags:
- name: Agents
paths:
/v1/agents:
post:
description: "General Translation: General Translation API provides large model-based multilingual translation services, including general translation, paraphrase translation, two-step translation, and three-pass translation strategies. It supports automatic language detection, glossary customization, translation suggestions, and streaming output. Users only need to call the Translation API, input the text to be processed, specify the source language (auto-detection supported) and target language to receive high-quality translation results. \n\n Popular Special Effects Videos: Popular special effects videos are intelligent templates launched based on trending features from pan-entertainment platforms, designed to precisely adapt to short video creative production needs. Currently, three effect templates are available: `French Kiss`, `Body Shake Dance`, and `Sexy Me`. After selecting a template, users only need to upload an image and enter corresponding prompts to generate a special effects video. \n\n GLM Slide/Poster Agent: An intelligent creation agent built for working people and creators. It goes beyond traditional engineering-style assembly tools—supporting one-click generation of slides or posters from natural language instructions. By natively integrating content generation with layout aesthetics and design conventions, it helps you quickly produce polished, professional-grade materials while lowering design barriers and boosting creative efficiency."
parameters:
- $ref: '#/components/parameters/AcceptLanguage'
requestBody:
content:
application/json:
schema:
oneOf:
- title: General Translation
$ref: '#/components/schemas/TranslationAgentRequest'
- title: Popular Special Effects Videos
$ref: '#/components/schemas/SpecialEffectsVideosAgentRequest'
- title: GLM Slide/Poster
$ref: '#/components/schemas/GlmSlideAgentRequest'
required: true
responses:
'200':
description: Processing successful
content:
application/json:
schema:
oneOf:
- title: General Translation
$ref: '#/components/schemas/TranslationAgentResponse'
- title: Popular Special Effects Videos
$ref: '#/components/schemas/SpecialEffectsVideosAgentResponse'
- title: GLM Slide/Poster
$ref: '#/components/schemas/GlmSlideAgentResponse'
examples:
General Translation:
value:
id: <string>
agent_id: <string>
choices:
- index: 123
finish_reason: <string>
messages:
- role: <string>
content:
text: <string>
type: <string>
usage:
prompt_tokens: 123
completion_tokens: 123
total_tokens: 123
total_calls: 123
Popular Special Effects Videos:
value:
status: <string>
agent_id: <string>
async_id: <string>
default:
description: The request has failed.
content:
application/json:
schema:
oneOf:
- title: General Translation
$ref: '#/components/schemas/Error'
- title: Popular Special Effects Videos
$ref: '#/components/schemas/SpecialEffectsVideosAgentError'
examples:
General Translation:
value:
code: 123
message: <string>
Popular Special Effects Videos:
value:
status: <string>
agent_id: <string>
error:
code: <string>
message: <string>
tags:
- Agents
/v1/agents/async-result:
post:
description: This endpoint is used to query the result of an asynchronous request.
parameters:
- $ref: '#/components/parameters/AcceptLanguage'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CommonAgentResultRequest'
required: true
responses:
'200':
description: Processing successful
content:
application/json:
schema:
$ref: '#/components/schemas/CommonAgentResultResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/SpecialEffectsVideosAgentError'
tags:
- Agents
/v1/agents/conversation:
post:
description: This endpoint is used to query the agent conversation history.Only support slides_glm_agent
parameters:
- $ref: '#/components/parameters/AcceptLanguage'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GlmSlideAgentConversationRequest'
required: true
responses:
'200':
description: Processing successful
content:
application/json:
schema:
$ref: '#/components/schemas/GlmSlideAgentConversationResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Agents
components:
parameters:
AcceptLanguage:
name: Accept-Language
in: header
schema:
type: string
description: Config desired response language for HTTP requests.
default: en-US,en
example: en-US,en
enum:
- en-US,en
required: false
schemas:
GlmSlideAgentConversationResponse:
type: object
properties:
conversation_id:
type: string
description: Conversation ID
agent_id:
type: string
description: Agent ID
choices:
type: array
description: Agent output.
items:
type: object
properties:
message:
type: array
items:
type: object
properties:
role:
type: string
description: 'Role: fixed as `assistant`.'
content:
type: array
description: Content metadata
items:
type: object
properties:
type:
type: string
description: 'Response Content type: file_url、image_url'
tag_cn:
type: string
description: CN Tag.
tag_en:
type: string
description: EN Tag.
file_url:
type: string
description: Output file_url content when type is file_url
image_url:
type: string
description: Output image_url content when type is image_url
error:
type: object
properties:
code:
type: string
description: Error code.
message:
type: string
description: Error message.
GlmSlideAgentResponse:
type: object
properties:
id:
type: string
description: Request ID
conversation_id:
type: string
description: Conversation ID
agent_id:
type: string
description: Agent ID
choices:
type: array
description: Agent output.
items:
type: object
properties:
index:
type: integer
description: Result index.
finish_reason:
type: string
description: Reason for model inference termination. Can be ‘stop’, ‘tool_calls’, ‘length’, ‘sensitive’, or ‘network_error’.
message:
type: array
items:
type: object
properties:
role:
type: string
description: 'Role: fixed as `assistant`.'
phase:
type: string
description: 'Current role type: thinking、tool、answer'
content:
type: array
description: Content metadata
items:
type: object
properties:
type:
type: string
description: 'Response Content type: text、object'
tag_cn:
type: string
description: CN Tag.
tag_en:
type: string
description: EN Tag.
text:
type: string
description: Output string content when type is text
object:
type: object
description: Output object content when type is object
properties:
tool_name:
type: string
description: 'Tool name eg: search、insert_page'
input:
type: string
description: Tool input content
output:
type: string
description: Tool output content, will output html when generate slide
position:
type: array
description: "If the tool involves operations on a PPT file, the position field specifies which slides are being manipulated.\n If the user says, “Insert a slide after the second slide,” then position = [3], and the output is the HTML content of the third slide.\n If the user says, “Please delete slides 4, 5, and 6,” then position = [4, 5, 6]."
items:
type: number
error:
type: object
properties:
code:
type: string
description: Error code.
message:
type: string
description: Error message.
SpecialEffectsVideosAgentResponse:
allOf:
- type: object
properties:
async_id:
type: string
description: Asynchronous task ID.
- $ref: '#/components/schemas/SpecialEffectsVideosAgentError'
CommonAgentResultRequest:
type: object
properties:
agent_id:
type: string
description: 'Agent ID: `vidu_template_agent`.'
async_id:
type: string
description: Task ID from async response.
SpecialEffectsVideosAgentError:
type: object
properties:
status:
type: string
description: 'Status: `pending` (task created), `failed` (task creation failed).'
agent_id:
type: string
description: Agent ID
error:
type: object
properties:
code:
type: string
description: Error code.
message:
type: string
description: Error message.
Error:
required:
- code
- message
type: object
description: The request has failed.
properties:
code:
type: integer
format: int32
description: Error code.
message:
type: string
description: Error message.
GlmSlideAgentConversationRequest:
type: object
properties:
agent_id:
type: string
description: Agent ID
conversation_id:
type: string
description: Conversation ID
custom_variables:
type: object
description: Custom variables
properties:
include_pdf:
type: boolean
description: Is export the pdf file
pages:
type: array
description: Slides Pages
items:
type: object
properties:
position:
type: number
description: Slide Page Position
width:
type: number
description: 'Slide Width, unit: pt'
height:
type: number
description: 'Slide Height, unit: pt'
TranslationAgentResponse:
type: object
properties:
id:
type: string
description: Task ID.
agent_id:
type: string
description: Agent ID.
status:
type: string
description: Task status.
choices:
type: array
description: Model output content.
items:
type: object
properties:
index:
type: integer
description: Result index.
finish_reason:
type: string
description: 'Termination reason: `stop` (normal completion), `tool_calls` (model calls), `length` (token limit exceeded), `sensitive` (content flagged), `network_error` (model inference error).'
messages:
type: object
description: Model response message.
properties:
role:
type: string
description: 'Dialog role (default: `assistant`).'
content:
type: object
description: Inference result
properties:
type:
type: string
description: Result type.
text:
type: string
description: Result content.
usage:
type: object
description: Token usage statistics.
properties:
prompt_tokens:
type: integer
description: Input tokens count.
completion_tokens:
type: integer
description: Output tokens count.
total_tokens:
type: integer
description: Total tokens count.
total_calls:
type: integer
description: Total number of calls
GlmSlideAgentRequest:
type: object
properties:
agent_id:
type: string
description: Agent ID.
enum:
- slides_glm_agent
stream:
type: boolean
default: true
description: False for sync calls (default). True for streaming.
conversation_id:
type: string
description: Conversation Id.
request_id:
type: string
description: User-defined unique ID; used to distinguish requests. Auto-generated if omitted.
messages:
type: array
description: Message body.
items:
type: object
properties:
role:
type: string
description: 'User input role: `user`'
example: user
default: user
enum:
- user
content:
type: array
description: Content list.
items:
oneOf:
- title: text
type: object
properties:
type:
type: string
description: Specifies that this content is text.
enum:
- text
text:
type: string
description: User text input.
required:
- type
- text
required:
- role
- content
required:
- agent_id
- messages
CommonAgentResultResponse:
type: object
properties:
status:
type: string
description: '`pending` (processing), `success` (completed), `failed` (failed).'
agent_id:
type: string
description: Agent ID
async_id:
type: string
description: Asynchronous task ID.
choices:
type: array
description: Agent output.
items:
type: object
properties:
index:
type: integer
description: Result index.
finish_reason:
type: string
description: Reason for model inference termination. Can be ‘stop’, ‘tool_calls’, ‘length’, ‘sensitive’, or ‘network_error’.
message:
type: array
items:
type: object
properties:
role:
type: string
description: 'Role: fixed as `assistant`.'
content:
type: array
description: Video file metadata
items:
type: object
properties:
type:
type: string
description: 'object type: `video_url`.'
video_url:
type: string
description: MP4 video URL.
SpecialEffectsVideosAgentRequest:
type: object
properties:
agent_id:
type: string
description: 'Agent ID: `vidu_template_agent`.'
enum:
- vidu_template_agent
request_id:
type: string
description: User-defined unique ID; used to distinguish requests. Auto-generated if omitted.
messages:
type: array
description: Session message body.
items:
type: object
properties:
role:
type: string
description: 'User input role: `user`'
example: user
default: user
enum:
- user
content:
type: array
description: Content list.
items:
oneOf:
- title: text
type: object
properties:
type:
type: string
description: Specifies that this content is text.
enum:
- text
text:
type: string
description: User text input.
required:
- type
- text
- title: image_url
type: object
properties:
type:
type: string
description: Specifies that this content is an image URL.
enum:
- image_url
image_url:
type: string
format: uri
description: Image URL input.
required:
- type
- image_url
required:
- role
- content
custom_variables:
type: object
description: Agent extension parameters.
properties:
template:
type: string
description: 'Effect template: `french_kiss`, `bodyshake`, or `sexy_me`.'
enum:
- french_kiss
- bodyshake
- sexy_me
required:
- template
required:
- agent_id
- messages
TranslationAgentRequest:
type: object
properties:
agent_id:
type: string
description: 'Agent ID: `general_translation`.'
enum:
- general_translation
stream:
type: boolean
description: False for sync calls (default). True for streaming.
messages:
type: array
description: Session message body.
items:
type: object
properties:
role:
type: string
description: 'User input role: `user`'
example: user
default: user
enum:
- user
content:
type: array
description: Content list.
items:
type: object
properties:
type:
type: string
description: 'Supported type: `text`.'
default: text
enum:
- text
text:
type: string
description: User text input.
required:
- type
- text
required:
- role
- content
custom_variables:
type: object
properties:
source_lang:
type: string
description: 'Supported language codes (default: `auto`):
- `auto`: Auto Detect
- `zh-CN`: Simplified Chinese
- `zh-TW`: Traditional Chinese
- `wyw`: Classical Chinese
- `yue`: Cantonese
- `en`: English
- `ja`: Japanese
- `ko`: Korean
- `fr`: French
- `de`: German
- `es`: Spanish
- `ru`: Russian
- `pt`: Portuguese
- `it`: Italian
- `ar`: Arabic
- `hi`: Hindi
- `bg`: Bulgarian
- `cs`: Czech
- `da`: Danish
- `el`: Greek
- `et`: Estonian
- `fi`: Finnish
- `hu`: Hungarian
- `id`: Indonesian
- `lt`: Lithuanian
- `lv`: Latvian
- `nl`: Dutch
- `no`: Norwegian Bokmål
- `pl`: Polish
- `ro`: Romanian
- `sk`: Slovak
- `sl`: Slovenian
- `sv`: Swedish
- `th`: Thai
- `tr`: Turkish
- `uk`: Ukrainian
- `vi`: Vietnamese
- `my`: Burmese
- `ms`: Malay
- `Pinyin`: Pinyin
- `IPA`: International Phonetic Alphabet
'
enum:
- auto
- zh-CN
- zh-TW
- wyw
- yue
- en
- ja
- ko
- fr
- de
- es
- ru
- pt
- it
- ar
- hi
- bg
- cs
- da
- el
- et
- fi
- hu
- id
- lt
- lv
- nl
- 'no'
- pl
- ro
- sk
- sl
- sv
- th
- tr
- uk
- vi
- my
- ms
- Pinyin
- IPA
target_lang:
type: string
description: 'Target language code (default: `zh-CN`):
- `zh-CN`: Simplified Chinese
- `zh-TW`: Traditional Chinese
- `wyw`: Classical Chinese
- `yue`: Cantonese
- `en`: English
- `en-GB`: English (British)
- `en-US`: English (American)
- `ja`: Japanese
- `ko`: Korean
- `fr`: French
- `de`: German
- `es`: Spanish
- `ru`: Russian
- `pt`: Portuguese
- `it`: Italian
- `ar`: Arabic
- `hi`: Hindi
- `bg`: Bulgarian
- `cs`: Czech
- `da`: Danish
- `el`: Greek
- `et`: Estonian
- `fi`: Finnish
- `hu`: Hungarian
- `id`: Indonesian
- `lt`: Lithuanian
- `lv`: Latvian
- `nl`: Dutch
- `no`: Norwegian Bokmål
- `pl`: Polish
- `ro`: Romanian
- `sk`: Slovak
- `sl`: Slovenian
- `sv`: Swedish
- `th`: Thai
- `tr`: Turkish
- `uk`: Ukrainian
- `vi`: Vietnamese
- `my`: Burmese
- `ms`: Malay
- `Pinyin`: Pinyin
- `IPA`: International Phonetic Alphabet
.'
enum:
- zh-CN
- zh-TW
- wyw
- yue
- en
- en-GB
- en-US
- ja
- ko
- fr
- de
- es
- ru
- pt
- it
- ar
- hi
- bg
- cs
- da
- el
- et
- fi
- hu
- id
- lt
- lv
- nl
- 'no'
- pl
- ro
- sk
- sl
- sv
- th
- tr
- uk
- vi
- my
- ms
- Pinyin
- IPA
glossary:
type: string
description: Glossary ID.
strategy:
type: string
description: 'Translation strategy (default: `general`)，Optional:
- `general`: General Translation
- `paraphrase`: Paraphrase Translation
- `two_step`: Two-Step Translation
- `three_step`: Three-Stage Translation
- `reflection`: Reflection Translation; cot: COT Translation'
enum:
- general
- paraphrase
- two_step
- three_step
- reflection
strategy_config:
type: object
description: Strategy parameters.
properties:
general:
type: object
properties:
suggestion:
type: string
description: Translation suggestions or style requirements (e.g., terminology mapping, style guidelines).
cot:
type: object
description: Parameters when strategy is `cot`.
properties:
reason_lang:
type: string
description: 'Language for translation reasoning, values: [`from`｜`to`], default: `to`.'
enum:
- from
- to
required:
- agent_id
- messages
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Use the following format for authentication: Bearer [<your api key>](https://z.ai/manage-apikey/apikey-list)'