模型服务接口文档

文本对话和视频生成，按实际用量从模型服务余额扣费；Codex、Claude Code、CC Switch 等工具可直接接入。

适合：需要在自己的程序或开发工具里调用大模型的开发者

服务地址: https://www.zhugejunshi.com/api
鉴权: Authorization: Bearer zg_live_…
接口数量: 11 个 · 文档版本 v1
文档文件: model-gateway.json（OpenAPI，可导入 Postman、Apifox 等工具）

使用须知

每个密钥有每分钟 token 上限，新建密钥默认每分钟 200 万 token，超出返回 429（RATE_LIMITED）。
余额不足或达到密钥消费上限时返回 402，可在模型服务页充值或调整上限。
一次对话最多 200 条消息、128 个工具；只转发文本，图片和文件不会转给模型。
视频时长 4–15 秒，提交后异步生成；建议带 Idempotency-Key 防止重复提交。

文本对话和视频生成接口，按实际用量从模型服务余额扣费。对话接口同时提供 Chat Completions、Responses、Messages 三种常见请求格式，Codex、Claude Code、CC Switch 等工具填上服务地址和密钥即可直接使用。密钥在 /model 页创建，形如 zg_live_…，完整密钥只在创建时显示一次。

模型与对话

查询可用模型、发起文本对话。支持流式返回（stream: true，按 text/event-stream 推送）。

GET列出可用模型

/v1/models

需要密钥 · 需要权限 models:read

返回当前密钥可以调用的模型。调用对话接口时把其中的 id 填进 model 字段。

200模型列表

200 的返回字段
字段	类型	必填	说明
`object`	`string`	否	可选值：list
`data`	`array<object>`	否	—
`data[].id`	`string`	否	模型名，调用时填写。
`data[].object`	`string`	否	可选值：model
`data[].owned_by`	`string`	否	—
`data[].capability`	`string`	否	模型用途，例如 text、video。

返回示例

{
  "object": "list",
  "data": [
    {
      "id": "zhuge-text-fast",
      "object": "model",
      "owned_by": "zhuge",
      "capability": "text"
    }
  ]
}

401密钥缺失或无效

401 的返回字段
字段	类型	必填	说明
`error`	`object`	否	—
`error.code`	`string`	是	英文错误码，例如 INVALID_API_KEY、SCOPE_DENIED、MODEL_NOT_FOUND。
`error.message`	`string`	是	中文说明。
`error.request_id`	`string`	否	请求编号，联系客服时请提供。
`error.retryable`	`boolean`	否	为 true 时可以稍后重试。

403密钥没有调用该接口的权限

返回字段同 401。

错误返回的格式和重试建议见错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/v1/models' \
  -H 'Authorization: Bearer YOUR_API_KEY'

在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里，不保存、不上传到别处，刷新页面后要重新填写。

密钥（zg_live_…）

POST文本对话（Chat Completions）

/v1/chat/completions

需要密钥 · 需要权限 inference:write

按 messages 对话记录生成回答。支持工具调用（tools）、JSON 输出（response_format）和流式返回。只接受文本内容，图片、文件不会转给模型。返回头 X-Zhuge-Request-Id 是本次请求编号。

请求内容（application/json，必填）

文本对话（Chat Completions）的请求字段
字段	类型	必填	说明
`model`	`string`	是	模型名，见 GET /v1/models。长度 1–200
`messages`	`array<ChatMessage>`	是	1–200 项
`messages[].role`	`string`	是	可选值：system / developer / user / assistant / tool
`messages[].content`	`string \| array<TextPart> \| null`	否	文本，或文本块数组。
`messages[].tool_call_id`	`string`	否	role 为 tool 时，对应的工具调用 id。
`messages[].tool_calls`	`array<ToolCall>`	否	最多 128 项
`messages[].tool_calls[].id`	`string`	是	长度 1–200
`messages[].tool_calls[].type`	`string`	是	可选值：function
`messages[].tool_calls[].function`	`object`	是	—
`messages[].tool_calls[].function.name`	`string`	是	长度 1–128
`messages[].tool_calls[].function.arguments`	`string`	是	JSON 字符串。最长 250000
`messages[].reasoning_content`	`string`	否	模型的思考内容（部分模型返回）。最长 250000
`messages[].name`	`string`	否	最长 128
`stream`	`boolean`	否	为 true 时按 text/event-stream 流式返回。默认：false
`stream_options`	`object`	否	—
`stream_options.include_usage`	`boolean`	否	流式结束前推送一次用量。默认：true
`max_tokens`	`integer`	否	回答的最大 token 数。范围：1 到 1048576
`max_total_tokens`	`integer`	否	输入加回答的 token 上限。范围：1 到 1048576
`reasoning_effort`	`string`	否	思考强度。可选值：none / minimal / low / medium / high / xhigh / max
`response_format`	`object`	否	—
`response_format.type`	`string`	是	可选值：text / json_object / json_schema
`response_format.json_schema`	`object`	否	type 为 json_schema 时的结构定义。
`temperature`	`number`	否	范围：0 到 2
`top_p`	`number`	否	范围：0 到 1
`stop`	`string \| array<string>`	否	遇到这些文本时停止。
`tools`	`array<object>`	否	最多 128 项
`tools[].type`	`string`	是	可选值：function
`tools[].function`	`object`	是	—
`tools[].function.name`	`string`	是	长度 1–128
`tools[].function.description`	`string`	否	最长 32000
`tools[].function.parameters`	`object`	是	JSON Schema。
`tools[].function.strict`	`boolean`	否	—
`tool_choice`	`string \| object`	否	—
`parallel_tool_calls`	`boolean`	否	—

请求示例

{
  "model": "zhuge-text-fast",
  "messages": [
    {
      "role": "system",
      "content": "你是一名简洁的助手。"
    },
    {
      "role": "user",
      "content": "用一句话介绍你自己。"
    }
  ],
  "max_tokens": 1024,
  "stream": false
}

200非流式时返回完整回答；stream 为 true 时返回 text/event-stream，每条 data 是一段增量，最后是 data: [DONE]。

200 的返回字段
字段	类型	必填	说明
`id`	`string`	否	—
`object`	`string`	否	可选值：chat.completion
`created`	`integer`	否	Unix 秒。
`model`	`string`	否	—
`choices`	`array<object>`	否	—
`choices[].index`	`integer`	否	—
`choices[].message`	`ChatMessage`	否	—
`choices[].message.role`	`string`	是	可选值：system / developer / user / assistant / tool
`choices[].message.content`	`string \| array<TextPart> \| null`	否	文本，或文本块数组。
`choices[].message.tool_call_id`	`string`	否	role 为 tool 时，对应的工具调用 id。
`choices[].message.tool_calls`	`array<ToolCall>`	否	最多 128 项
`choices[].message.tool_calls[].id`	`string`	是	长度 1–200
`choices[].message.tool_calls[].type`	`string`	是	可选值：function
`choices[].message.tool_calls[].function`	`object`	是	—
`choices[].message.tool_calls[].function.name`	`string`	是	长度 1–128
`choices[].message.tool_calls[].function.arguments`	`string`	是	JSON 字符串。最长 250000
`choices[].message.reasoning_content`	`string`	否	模型的思考内容（部分模型返回）。最长 250000
`choices[].message.name`	`string`	否	最长 128
`choices[].finish_reason`	`string`	否	stop 正常结束；length 达到长度上限；tool_calls 需要调用工具。
`usage`	`object`	否	—
`usage.prompt_tokens`	`integer`	否	—
`usage.completion_tokens`	`integer`	否	—
`usage.total_tokens`	`integer`	否	—

返回示例

{
  "id": "chatcmpl-0123456789",
  "object": "chat.completion",
  "created": 1762502400,
  "model": "zhuge-text-fast",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "我是诸葛军师模型服务的助手。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 12,
    "total_tokens": 36
  }
}

400请求内容有误，例如超出模型的上下文长度（CONTEXT_LIMIT_EXCEEDED）

400 的返回字段
字段	类型	必填	说明
`error`	`object`	否	—
`error.code`	`string`	是	英文错误码，例如 INVALID_API_KEY、SCOPE_DENIED、MODEL_NOT_FOUND。
`error.message`	`string`	是	中文说明。
`error.request_id`	`string`	否	请求编号，联系客服时请提供。
`error.retryable`	`boolean`	否	为 true 时可以稍后重试。

401密钥缺失或无效

返回字段同 400。

402余额不足（INSUFFICIENT_BALANCE）或达到密钥的消费上限（KEY_SPEND_LIMIT_REACHED），请到 /model 充值或调整上限

返回字段同 400。

403密钥没有调用该接口的权限

返回字段同 400。

404模型不存在或已下线

返回字段同 400。

429超出调用频率或每分钟 token 上限，请稍后重试

返回字段同 400。

503服务暂不可用，可以稍后重试

返回字段同 400。

错误返回的格式和重试建议见错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "zhuge-text-fast",
  "messages": [
    {
      "role": "system",
      "content": "你是一名简洁的助手。"
    },
    {
      "role": "user",
      "content": "用一句话介绍你自己。"
    }
  ],
  "max_tokens": 1024,
  "stream": false
}'

POST文本对话（Responses 格式）

/v1/responses

需要密钥 · 需要权限 inference:write

Responses 请求格式，给 Codex 等工具使用：wire_api 设为 responses，base_url 填 https://www.zhugejunshi.com/api/v1。支持文本和函数工具，流式、非流式都可以。服务端不保存对话：不支持 previous_response_id，请在 input 里带上完整对话（store=false）。图片、文件和联网搜索等托管工具不会转给模型。

请求内容（application/json，必填）

文本对话（Responses 格式）的请求字段
字段	类型	必填	说明
`model`	`string`	是	模型名。
`input`	`any`	是	字符串，或对话条目数组（role + content）。不能为空。
`instructions`	`string`	否	系统提示。
`tools`	`array<object>`	否	函数工具；自定义工具按一个 input 字符串参数提供。
`stream`	`boolean`	否	默认：false
`max_output_tokens`	`integer`	否	回答的最大 token 数。

请求示例

{
  "model": "zhuge-text-fast",
  "input": "写一句欢迎语。",
  "stream": false
}

200Responses 格式的回答；流式时按 response.* 事件推送，最后是 response.completed。

没有返回内容。

400请求有误：缺少 model、input 为空或带了 previous_response_id

400 的返回字段
字段	类型	必填	说明
`error`	`object`	否	—
`error.code`	`string`	是	英文错误码，例如 INVALID_API_KEY、SCOPE_DENIED、MODEL_NOT_FOUND。
`error.message`	`string`	是	中文说明。
`error.request_id`	`string`	否	请求编号，联系客服时请提供。
`error.retryable`	`boolean`	否	为 true 时可以稍后重试。

401没有带 Bearer 密钥

返回字段同 400。

503服务暂不可用，可以稍后重试

返回字段同 400。

错误返回的格式和重试建议见错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/v1/responses' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "zhuge-text-fast",
  "input": "写一句欢迎语。",
  "stream": false
}'

POST文本对话（Messages 格式）

/v1/messages

需要密钥 · 需要权限 inference:write

Messages 请求格式，给 Claude Code 等工具使用：服务地址填 https://www.zhugejunshi.com/api，密钥可以放在 Authorization: Bearer 或 x-api-key 请求头。支持文本和客户端工具，流式、非流式都可以；工具默认的模型名会由本服务的文本模型回答。图片、文档和服务端工具不会转给模型。

请求内容（application/json，必填）

文本对话（Messages 格式）的请求字段
字段	类型	必填	说明
`model`	`string`	是	—
`messages`	`array<object>`	是	对话记录，每条有 role（user / assistant）和 content。
`system`	`any`	否	系统提示，字符串或文本块数组。
`max_tokens`	`integer`	是	—
`tools`	`array<object>`	否	—
`stream`	`boolean`	否	默认：false

请求示例

{
  "model": "zhuge-text-fast",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}

200Messages 格式的回答；流式时按 message_start / content_block_delta / message_stop 等事件推送。

没有返回内容。

401没有带密钥。

没有返回内容。

503模型服务暂不可用。

没有返回内容。

错误返回的格式和重试建议见错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "zhuge-text-fast",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}'

POST估算 Messages 请求的 token 数

/v1/messages/count_tokens

需要密钥 · 需要权限 inference:write

请求体与 /v1/messages 相同，返回估算的输入 token 数，不调用模型、不扣费。

请求内容（application/json，必填）

估算 Messages 请求的 token 数的请求字段
字段	类型	必填	说明
`model`	`string`	是	—
`messages`	`array<object>`	是	—

请求示例

{
  "model": "zhuge-text-fast",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}

200估算结果

200 的返回字段
字段	类型	必填	说明
`input_tokens`	`integer`	否	—

返回示例

{
  "input_tokens": 9
}

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/v1/messages/count_tokens' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "zhuge-text-fast",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}'

视频生成

提交视频任务后异步生成，按秒计价；用任务编号查询进度并下载成片。

GET查询视频价格

/v1/videos/pricing

需要密钥

按分辨率和是否快速模式（turbo_mode）列出每秒价格，单位人民币元。

200价格表

200 的返回字段
字段	类型	必填	说明
`currency`	`string`	否	可选值：CNY
`unit`	`string`	否	可选值：second
`version`	`string`	否	价格版本。
`workflows`	`array<string>`	否	可用的生成方式。
`variants`	`array<object>`	否	—
`variants[].resolution`	`string`	否	—
`variants[].turbo_mode`	`boolean`	否	—
`variants[].price`	`string`	否	每秒价格（元）。

返回示例

{
  "currency": "CNY",
  "unit": "second",
  "version": "2026-10",
  "workflows": [
    "h3-official-t2v",
    "h3-official-i2v",
    "h3-official-r2v"
  ],
  "variants": [
    {
      "resolution": "768p",
      "turbo_mode": false,
      "price": "0.50"
    }
  ]
}

401密钥缺失或无效

401 的返回字段
字段	类型	必填	说明
`error`	`object`	否	—
`error.code`	`string`	是	英文错误码，例如 INVALID_API_KEY、SCOPE_DENIED、MODEL_NOT_FOUND。
`error.message`	`string`	是	中文说明。
`error.request_id`	`string`	否	请求编号，联系客服时请提供。
`error.retryable`	`boolean`	否	为 true 时可以稍后重试。

404当前密钥没有可用的视频模型

返回字段同 401。

错误返回的格式和重试建议见错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/v1/videos/pricing' \
  -H 'Authorization: Bearer YOUR_API_KEY'

在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里，不保存、不上传到别处，刷新页面后要重新填写。

密钥（zg_live_…）

GET列出视频任务

/v1/videos

需要密钥

按提交时间倒序返回最近的视频任务。

200任务列表

200 的返回字段
字段	类型	必填	说明
`object`	`string`	否	可选值：list
`data`	`array<Video>`	否	—
`data[].id`	`string（uuid）`	否	—
`data[].object`	`string`	否	可选值：video
`data[].model`	`string`	否	—
`data[].status`	`string`	否	任务状态：提交后为 queued，完成后为 completed。
`data[].progress`	`integer`	否	进度 0–100。
`data[].seconds`	`integer`	否	—
`data[].resolution`	`string`	否	—
`data[].turbo_mode`	`boolean`	否	—
`data[].workflow_type`	`string`	否	—
`data[].ratio`	`string \| null`	否	—
`data[].created_at`	`integer`	否	提交时间，Unix 秒。
`data[].completed_at`	`integer \| null`	否	—
`data[].billing`	`object`	否	金额单位是百万分之一元（micro_cny）。
`data[].billing.currency`	`string`	否	—
`data[].billing.estimated_micro_cny`	`integer`	否	—
`data[].billing.charged_micro_cny`	`integer`	否	—
`data[].billing.reserved_micro_cny`	`integer`	否	—
`data[].media`	`object \| null`	否	—
`data[].media.status`	`string`	否	—
`data[].media.has_frame`	`boolean`	否	—
`data[].media.expires_at`	`integer \| null`	否	成片保存截止时间，Unix 秒。
`data[].error`	`object \| null`	否	失败原因，未失败时为 null。
`data[].error.code`	`string`	否	—
`data[].error.message`	`string`	否	—
`data[].error.reason`	`string`	否	—

返回示例

{
  "object": "list",
  "data": []
}

401密钥缺失或无效

401 的返回字段
字段	类型	必填	说明
`error`	`object`	否	—
`error.code`	`string`	是	英文错误码，例如 INVALID_API_KEY、SCOPE_DENIED、MODEL_NOT_FOUND。
`error.message`	`string`	是	中文说明。
`error.request_id`	`string`	否	请求编号，联系客服时请提供。
`error.retryable`	`boolean`	否	为 true 时可以稍后重试。

错误返回的格式和重试建议见错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/v1/videos' \
  -H 'Authorization: Bearer YOUR_API_KEY'

在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里，不保存、不上传到别处，刷新页面后要重新填写。

密钥（zg_live_…）

POST提交视频任务

/v1/videos

需要密钥

提交后立即返回任务（状态 queued），生成在后台进行，用 GET /v1/videos/{video_id} 查询。提交时按价格预留费用，完成后按实际结算。建议带 Idempotency-Key 请求头，网络重试时不会重复创建任务。图片可用 data URL 或图片地址。

请求参数

提交视频任务的请求参数
参数	位置	类型	必填	说明
`Idempotency-Key`	请求头	`string`	否	幂等键，同一个键只创建一次任务。最长 200

请求内容（application/json，必填）

提交视频任务的请求字段
字段	类型	必填	说明
`model`	`string`	否	可选值：h3-video；默认：h3-video
`prompt`	`string`	是	画面描述。长度 1–4000
`seconds`	`integer`	否	时长（秒）。范围：4 到 15；默认：5
`resolution`	`string`	否	分辨率，例如 480p、768p、2k；可选值见价格接口。
`ratio`	`string`	否	画面比例，例如 16:9、9:16、1:1。
`workflow_type`	`string`	否	生成方式：h3-official-t2v 文生视频、h3-official-i2v 图生视频、h3-official-r2v 参考图生视频。
`first_frame`	`string`	否	首帧图片（data URL 或图片地址）。
`last_frame`	`string`	否	尾帧图片。
`reference_images`	`array<string>`	否	参考图。至少 1 项

请求示例

{
  "model": "h3-video",
  "prompt": "清晨的江边，薄雾里一只白鹭起飞，镜头缓慢推进。",
  "seconds": 5,
  "resolution": "768p",
  "ratio": "16:9"
}

202任务已受理

202 的返回字段
字段	类型	必填	说明
`id`	`string（uuid）`	否	—
`object`	`string`	否	可选值：video
`model`	`string`	否	—
`status`	`string`	否	任务状态：提交后为 queued，完成后为 completed。
`progress`	`integer`	否	进度 0–100。
`seconds`	`integer`	否	—
`resolution`	`string`	否	—
`turbo_mode`	`boolean`	否	—
`workflow_type`	`string`	否	—
`ratio`	`string \| null`	否	—
`created_at`	`integer`	否	提交时间，Unix 秒。
`completed_at`	`integer \| null`	否	—
`billing`	`object`	否	金额单位是百万分之一元（micro_cny）。
`billing.currency`	`string`	否	—
`billing.estimated_micro_cny`	`integer`	否	—
`billing.charged_micro_cny`	`integer`	否	—
`billing.reserved_micro_cny`	`integer`	否	—
`media`	`object \| null`	否	—
`media.status`	`string`	否	—
`media.has_frame`	`boolean`	否	—
`media.expires_at`	`integer \| null`	否	成片保存截止时间，Unix 秒。
`error`	`object \| null`	否	失败原因，未失败时为 null。
`error.code`	`string`	否	—
`error.message`	`string`	否	—
`error.reason`	`string`	否	—

返回示例

{
  "id": "6f1c2a4e-1d2b-4c3a-9e8f-0a1b2c3d4e5f",
  "object": "video",
  "model": "h3-video",
  "status": "queued",
  "progress": 0,
  "seconds": 5,
  "resolution": "768p",
  "turbo_mode": false,
  "workflow_type": "h3-official-t2v",
  "ratio": "16:9",
  "created_at": 1762502400,
  "completed_at": null,
  "billing": {
    "currency": "CNY",
    "estimated_micro_cny": 2500000,
    "charged_micro_cny": 0,
    "reserved_micro_cny": 2500000
  },
  "media": null,
  "error": null
}

400请求字段有误

400 的返回字段
字段	类型	必填	说明
`error`	`object`	否	—
`error.code`	`string`	是	英文错误码，例如 INVALID_API_KEY、SCOPE_DENIED、MODEL_NOT_FOUND。
`error.message`	`string`	是	中文说明。
`error.request_id`	`string`	否	请求编号，联系客服时请提供。
`error.retryable`	`boolean`	否	为 true 时可以稍后重试。

401密钥缺失或无效

返回字段同 400。

402余额不足（INSUFFICIENT_BALANCE）或达到密钥的消费上限（KEY_SPEND_LIMIT_REACHED），请到 /model 充值或调整上限

返回字段同 400。

409同一个 Idempotency-Key 用在了内容不同的请求上

返回字段同 400。

429视频任务提交过快或同时进行的任务太多

返回字段同 400。

503视频服务暂不可用

返回字段同 400。

错误返回的格式和重试建议见错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/v1/videos' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "h3-video",
  "prompt": "清晨的江边，薄雾里一只白鹭起飞，镜头缓慢推进。",
  "seconds": 5,
  "resolution": "768p",
  "ratio": "16:9"
}'

GET查询视频任务

/v1/videos/{video_id}

需要密钥

返回任务状态、进度、计费和成片保存情况。成片生成后用 /content 下载。

请求参数

查询视频任务的请求参数
参数	位置	类型	必填	说明
`video_id`	路径	`string（uuid）`	是	提交任务时返回的 id。

200任务详情

200 的返回字段
字段	类型	必填	说明
`id`	`string（uuid）`	否	—
`object`	`string`	否	可选值：video
`model`	`string`	否	—
`status`	`string`	否	任务状态：提交后为 queued，完成后为 completed。
`progress`	`integer`	否	进度 0–100。
`seconds`	`integer`	否	—
`resolution`	`string`	否	—
`turbo_mode`	`boolean`	否	—
`workflow_type`	`string`	否	—
`ratio`	`string \| null`	否	—
`created_at`	`integer`	否	提交时间，Unix 秒。
`completed_at`	`integer \| null`	否	—
`billing`	`object`	否	金额单位是百万分之一元（micro_cny）。
`billing.currency`	`string`	否	—
`billing.estimated_micro_cny`	`integer`	否	—
`billing.charged_micro_cny`	`integer`	否	—
`billing.reserved_micro_cny`	`integer`	否	—
`media`	`object \| null`	否	—
`media.status`	`string`	否	—
`media.has_frame`	`boolean`	否	—
`media.expires_at`	`integer \| null`	否	成片保存截止时间，Unix 秒。
`error`	`object \| null`	否	失败原因，未失败时为 null。
`error.code`	`string`	否	—
`error.message`	`string`	否	—
`error.reason`	`string`	否	—

返回示例

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object": "video",
  "model": "model",
  "status": "status"
}

401密钥缺失或无效

401 的返回字段
字段	类型	必填	说明
`error`	`object`	否	—
`error.code`	`string`	是	英文错误码，例如 INVALID_API_KEY、SCOPE_DENIED、MODEL_NOT_FOUND。
`error.message`	`string`	是	中文说明。
`error.request_id`	`string`	否	请求编号，联系客服时请提供。
`error.retryable`	`boolean`	否	为 true 时可以稍后重试。

404任务不存在或不属于当前账户

返回字段同 401。

错误返回的格式和重试建议见错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/v1/videos/{video_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里，不保存、不上传到别处，刷新页面后要重新填写。

密钥（zg_live_…）video_id（路径参数，必填）

GET下载成片

/v1/videos/{video_id}/content

需要密钥

返回 MP4 文件。成片保存有期限（见任务的 media.expires_at），过期后无法下载。

请求参数

下载成片的请求参数
参数	位置	类型	必填	说明
`video_id`	路径	`string（uuid）`	是	—

200video/mp4 文件

没有返回内容。

401密钥缺失或无效

401 的返回字段
字段	类型	必填	说明
`error`	`object`	否	—
`error.code`	`string`	是	英文错误码，例如 INVALID_API_KEY、SCOPE_DENIED、MODEL_NOT_FOUND。
`error.message`	`string`	是	中文说明。
`error.request_id`	`string`	否	请求编号，联系客服时请提供。
`error.retryable`	`boolean`	否	为 true 时可以稍后重试。

404任务不存在、未完成或成片已过期。

没有返回内容。

错误返回的格式和重试建议见错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/v1/videos/{video_id}/content' \
  -H 'Authorization: Bearer YOUR_API_KEY'

在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里，不保存、不上传到别处，刷新页面后要重新填写。

密钥（zg_live_…）video_id（路径参数，必填）

GET下载成片末帧

/v1/videos/{video_id}/frame

需要密钥

返回成片最后一帧的 JPEG，可作为下一段视频的首帧。

请求参数

下载成片末帧的请求参数
参数	位置	类型	必填	说明
`video_id`	路径	`string（uuid）`	是	—

200image/jpeg 文件

没有返回内容。

401密钥缺失或无效

401 的返回字段
字段	类型	必填	说明
`error`	`object`	否	—
`error.code`	`string`	是	英文错误码，例如 INVALID_API_KEY、SCOPE_DENIED、MODEL_NOT_FOUND。
`error.message`	`string`	是	中文说明。
`error.request_id`	`string`	否	请求编号，联系客服时请提供。
`error.retryable`	`boolean`	否	为 true 时可以稍后重试。

404任务不存在或没有末帧。

没有返回内容。

错误返回的格式和重试建议见错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/v1/videos/{video_id}/frame' \
  -H 'Authorization: Bearer YOUR_API_KEY'

在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里，不保存、不上传到别处，刷新页面后要重新填写。

密钥（zg_live_…）video_id（路径参数，必填）

使用须知

模型与对话

返回

调用示例

请求内容 （application/json，必填）

返回

调用示例

请求内容 （application/json，必填）

返回

调用示例

请求内容 （application/json，必填）

返回

调用示例

请求内容 （application/json，必填）

返回

调用示例

视频生成

返回

调用示例

返回

调用示例

请求参数

请求内容 （application/json，必填）

返回

调用示例

请求参数

返回

调用示例

请求参数

返回

调用示例

请求参数

返回

调用示例

请求内容（application/json，必填）

请求内容（application/json，必填）

请求内容（application/json，必填）

请求内容（application/json，必填）

请求内容（application/json，必填）