{"openapi":"3.1.0","info":{"title":"诸葛军师模型服务接口","version":"v1","description":"文本对话和视频生成接口，按实际用量从模型服务余额扣费。对话接口同时提供 Chat Completions、Responses、Messages 三种常见请求格式，Codex、Claude Code、CC Switch 等工具填上服务地址和密钥即可直接使用。密钥在 /model 页创建，形如 zg_live_…，完整密钥只在创建时显示一次。"},"servers":[{"url":"https://www.zhugejunshi.com/api"}],"tags":[{"name":"模型与对话","description":"查询可用模型、发起文本对话。支持流式返回（stream: true，按 text/event-stream 推送）。"},{"name":"视频生成","description":"提交视频任务后异步生成，按秒计价；用任务编号查询进度并下载成片。"}],"security":[{"gatewayKey":[]}],"paths":{"/v1/models":{"get":{"tags":["模型与对话"],"summary":"列出可用模型","description":"返回当前密钥可以调用的模型。调用对话接口时把其中的 id 填进 model 字段。","x-scope":"models:read","responses":{"200":{"description":"模型列表","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"模型名，调用时填写。"},"object":{"type":"string","const":"model"},"owned_by":{"type":"string"},"capability":{"type":"string","description":"模型用途，例如 text、video。"}}}}}},"example":{"object":"list","data":[{"id":"zhuge-text-fast","object":"model","owned_by":"zhuge","capability":"text"}]}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/ScopeDenied"}}}},"/v1/chat/completions":{"post":{"tags":["模型与对话"],"summary":"文本对话（Chat Completions）","description":"按 messages 对话记录生成回答。支持工具调用（tools）、JSON 输出（response_format）和流式返回。只接受文本内容，图片、文件不会转给模型。返回头 X-Zhuge-Request-Id 是本次请求编号。","x-scope":"inference:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"},"example":{"model":"zhuge-text-fast","messages":[{"role":"system","content":"你是一名简洁的助手。"},{"role":"user","content":"用一句话介绍你自己。"}],"max_tokens":1024,"stream":false}}}},"responses":{"200":{"description":"非流式时返回完整回答；stream 为 true 时返回 text/event-stream，每条 data 是一段增量，最后是 data: [DONE]。","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"chat.completion"},"created":{"type":"integer","description":"Unix 秒。"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"$ref":"#/components/schemas/ChatMessage"},"finish_reason":{"type":"string","description":"stop 正常结束；length 达到长度上限；tool_calls 需要调用工具。"}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}},"example":{"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":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/InvalidKey"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/ScopeDenied"},"404":{"description":"模型不存在或已下线","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MODEL_NOT_FOUND","message":"请求的模型不可用。","request_id":"req_0123456789abcdef","retryable":false}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/responses":{"post":{"tags":["模型与对话"],"summary":"文本对话（Responses 格式）","description":"Responses 请求格式，给 Codex 等工具使用：wire_api 设为 responses，base_url 填 https://www.zhugejunshi.com/api/v1。支持文本和函数工具，流式、非流式都可以。服务端不保存对话：不支持 previous_response_id，请在 input 里带上完整对话（store=false）。图片、文件和联网搜索等托管工具不会转给模型。","x-scope":"inference:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string","description":"模型名。"},"input":{"description":"字符串，或对话条目数组（role + content）。不能为空。"},"instructions":{"type":"string","description":"系统提示。"},"tools":{"type":"array","items":{"type":"object"},"description":"函数工具；自定义工具按一个 input 字符串参数提供。"},"stream":{"type":"boolean","default":false},"max_output_tokens":{"type":"integer","description":"回答的最大 token 数。"}}},"example":{"model":"zhuge-text-fast","input":"写一句欢迎语。","stream":false}}}},"responses":{"200":{"description":"Responses 格式的回答；流式时按 response.* 事件推送，最后是 response.completed。"},"400":{"description":"请求有误：缺少 model、input 为空或带了 previous_response_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_model","message":"请指定模型。","request_id":"req_0123456789abcdef","retryable":false}}}}},"401":{"description":"没有带 Bearer 密钥","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_API_KEY","message":"请提供有效的网关 API 密钥。","request_id":"req_0123456789abcdef","retryable":false}}}}},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/messages":{"post":{"tags":["模型与对话"],"summary":"文本对话（Messages 格式）","description":"Messages 请求格式，给 Claude Code 等工具使用：服务地址填 https://www.zhugejunshi.com/api，密钥可以放在 Authorization: Bearer 或 x-api-key 请求头。支持文本和客户端工具，流式、非流式都可以；工具默认的模型名会由本服务的文本模型回答。图片、文档和服务端工具不会转给模型。","x-scope":"inference:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","messages","max_tokens"],"properties":{"model":{"type":"string"},"messages":{"type":"array","items":{"type":"object"},"description":"对话记录，每条有 role（user / assistant）和 content。"},"system":{"description":"系统提示，字符串或文本块数组。"},"max_tokens":{"type":"integer"},"tools":{"type":"array","items":{"type":"object"}},"stream":{"type":"boolean","default":false}}},"example":{"model":"zhuge-text-fast","max_tokens":1024,"messages":[{"role":"user","content":"你好"}]}}}},"responses":{"200":{"description":"Messages 格式的回答；流式时按 message_start / content_block_delta / message_stop 等事件推送。"},"401":{"description":"没有带密钥。"},"503":{"description":"模型服务暂不可用。"}}}},"/v1/messages/count_tokens":{"post":{"tags":["模型与对话"],"summary":"估算 Messages 请求的 token 数","description":"请求体与 /v1/messages 相同，返回估算的输入 token 数，不调用模型、不扣费。","x-scope":"inference:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string"},"messages":{"type":"array","items":{"type":"object"}}}},"example":{"model":"zhuge-text-fast","messages":[{"role":"user","content":"你好"}]}}}},"responses":{"200":{"description":"估算结果","content":{"application/json":{"schema":{"type":"object","properties":{"input_tokens":{"type":"integer"}}},"example":{"input_tokens":9}}}}}}},"/v1/videos/pricing":{"get":{"tags":["视频生成"],"summary":"查询视频价格","description":"按分辨率和是否快速模式（turbo_mode）列出每秒价格，单位人民币元。","responses":{"200":{"description":"价格表","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","const":"CNY"},"unit":{"type":"string","const":"second"},"version":{"type":"string","description":"价格版本。"},"workflows":{"type":"array","items":{"type":"string"},"description":"可用的生成方式。"},"variants":{"type":"array","items":{"type":"object","properties":{"resolution":{"type":"string"},"turbo_mode":{"type":"boolean"},"price":{"type":"string","description":"每秒价格（元）。"}}}}}},"example":{"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":{"$ref":"#/components/responses/InvalidKey"},"404":{"description":"当前密钥没有可用的视频模型","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MODEL_NOT_FOUND","message":"当前 Key 无可用的视频模型。","request_id":"req_0123456789abcdef","retryable":false}}}}}}}},"/v1/videos":{"post":{"tags":["视频生成"],"summary":"提交视频任务","description":"提交后立即返回任务（状态 queued），生成在后台进行，用 GET /v1/videos/{video_id} 查询。提交时按价格预留费用，完成后按实际结算。建议带 Idempotency-Key 请求头，网络重试时不会重复创建任务。图片可用 data URL 或图片地址。","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"幂等键，同一个键只创建一次任务。","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoRequest"},"example":{"model":"h3-video","prompt":"清晨的江边，薄雾里一只白鹭起飞，镜头缓慢推进。","seconds":5,"resolution":"768p","ratio":"16:9"}}}},"responses":{"202":{"description":"任务已受理","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"},"example":{"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":{"description":"请求字段有误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST","message":"seconds 需要在 4 到 15 之间。","request_id":"req_0123456789abcdef","retryable":false}}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"description":"同一个 Idempotency-Key 用在了内容不同的请求上","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"IDEMPOTENCY_CONFLICT","message":"幂等键已用于另一个请求。","request_id":"req_0123456789abcdef","retryable":false}}}}},"429":{"description":"视频任务提交过快或同时进行的任务太多","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VIDEO_CONCURRENCY_LIMIT","message":"同时进行的视频任务已达上限，请稍后再提交。","request_id":"req_0123456789abcdef","retryable":true}}}}},"503":{"description":"视频服务暂不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VIDEO_TEMPORARILY_UNAVAILABLE","message":"视频服务暂不可用，请稍后查询已有任务。","request_id":"req_0123456789abcdef","retryable":true}}}}}}},"get":{"tags":["视频生成"],"summary":"列出视频任务","description":"按提交时间倒序返回最近的视频任务。","responses":{"200":{"description":"任务列表","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Video"}}}},"example":{"object":"list","data":[]}}}},"401":{"$ref":"#/components/responses/InvalidKey"}}}},"/v1/videos/{video_id}":{"get":{"tags":["视频生成"],"summary":"查询视频任务","description":"返回任务状态、进度、计费和成片保存情况。成片生成后用 /content 下载。","parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"提交任务时返回的 id。"}],"responses":{"200":{"description":"任务详情","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"404":{"description":"任务不存在或不属于当前账户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VIDEO_NOT_FOUND","message":"视频任务不存在。","request_id":"req_0123456789abcdef","retryable":false}}}}}}}},"/v1/videos/{video_id}/content":{"get":{"tags":["视频生成"],"summary":"下载成片","description":"返回 MP4 文件。成片保存有期限（见任务的 media.expires_at），过期后无法下载。","parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"video/mp4 文件"},"401":{"$ref":"#/components/responses/InvalidKey"},"404":{"description":"任务不存在、未完成或成片已过期。"}}}},"/v1/videos/{video_id}/frame":{"get":{"tags":["视频生成"],"summary":"下载成片末帧","description":"返回成片最后一帧的 JPEG，可作为下一段视频的首帧。","parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"image/jpeg 文件"},"401":{"$ref":"#/components/responses/InvalidKey"},"404":{"description":"任务不存在或没有末帧。"}}}}},"components":{"securitySchemes":{"gatewayKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer zg_live_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"英文错误码，例如 INVALID_API_KEY、SCOPE_DENIED、MODEL_NOT_FOUND。"},"message":{"type":"string","description":"中文说明。"},"request_id":{"type":"string","description":"请求编号，联系客服时请提供。"},"retryable":{"type":"boolean","description":"为 true 时可以稍后重试。"}},"required":["code","message"]}}},"TextPart":{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","maxLength":250000}}},"ToolCall":{"type":"object","required":["id","type","function"],"properties":{"id":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","const":"function"},"function":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","minLength":1,"maxLength":128},"arguments":{"type":"string","description":"JSON 字符串。","maxLength":250000}}}}},"ChatMessage":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["system","developer","user","assistant","tool"]},"content":{"anyOf":[{"type":"string","maxLength":250000},{"type":"array","items":{"$ref":"#/components/schemas/TextPart"}},{"type":"null"}],"description":"文本，或文本块数组。"},"tool_call_id":{"type":"string","description":"role 为 tool 时，对应的工具调用 id。"},"tool_calls":{"type":"array","maxItems":128,"items":{"$ref":"#/components/schemas/ToolCall"}},"reasoning_content":{"type":"string","maxLength":250000,"description":"模型的思考内容（部分模型返回）。"},"name":{"type":"string","maxLength":128}}},"ChatRequest":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","minLength":1,"maxLength":200,"description":"模型名，见 GET /v1/models。"},"messages":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/ChatMessage"}},"stream":{"type":"boolean","default":false,"description":"为 true 时按 text/event-stream 流式返回。"},"stream_options":{"type":"object","properties":{"include_usage":{"type":"boolean","default":true,"description":"流式结束前推送一次用量。"}}},"max_tokens":{"type":"integer","minimum":1,"maximum":1048576,"description":"回答的最大 token 数。"},"max_total_tokens":{"type":"integer","minimum":1,"maximum":1048576,"description":"输入加回答的 token 上限。"},"reasoning_effort":{"type":"string","enum":["none","minimal","low","medium","high","xhigh","max"],"description":"思考强度。"},"response_format":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text","json_object","json_schema"]},"json_schema":{"type":"object","description":"type 为 json_schema 时的结构定义。"}}},"temperature":{"type":"number","minimum":0,"maximum":2},"top_p":{"type":"number","minimum":0,"maximum":1},"stop":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"遇到这些文本时停止。"},"tools":{"type":"array","maxItems":128,"items":{"type":"object","required":["type","function"],"properties":{"type":{"type":"string","const":"function"},"function":{"type":"object","required":["name","parameters"],"properties":{"name":{"type":"string","minLength":1,"maxLength":128},"description":{"type":"string","maxLength":32000},"parameters":{"type":"object","description":"JSON Schema。"},"strict":{"type":"boolean"}}}}}},"tool_choice":{"anyOf":[{"type":"string","enum":["auto","none","required"]},{"type":"object","properties":{"type":{"type":"string","const":"function"},"function":{"type":"object","properties":{"name":{"type":"string"}}}}}]},"parallel_tool_calls":{"type":"boolean"}}},"VideoRequest":{"type":"object","required":["prompt"],"properties":{"model":{"type":"string","const":"h3-video","default":"h3-video"},"prompt":{"type":"string","minLength":1,"maxLength":4000,"description":"画面描述。"},"seconds":{"type":"integer","minimum":4,"maximum":15,"default":5,"description":"时长（秒）。"},"resolution":{"type":"string","description":"分辨率，例如 480p、768p、2k；可选值见价格接口。"},"ratio":{"type":"string","description":"画面比例，例如 16:9、9:16、1:1。"},"workflow_type":{"type":"string","description":"生成方式：h3-official-t2v 文生视频、h3-official-i2v 图生视频、h3-official-r2v 参考图生视频。"},"first_frame":{"type":"string","description":"首帧图片（data URL 或图片地址）。"},"last_frame":{"type":"string","description":"尾帧图片。"},"reference_images":{"type":"array","items":{"type":"string"},"minItems":1,"description":"参考图。"}}},"Video":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"video"},"model":{"type":"string"},"status":{"type":"string","description":"任务状态：提交后为 queued，完成后为 completed。"},"progress":{"type":"integer","description":"进度 0–100。"},"seconds":{"type":"integer"},"resolution":{"type":"string"},"turbo_mode":{"type":"boolean"},"workflow_type":{"type":"string"},"ratio":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"integer","description":"提交时间，Unix 秒。"},"completed_at":{"anyOf":[{"type":"integer"},{"type":"null"}]},"billing":{"type":"object","description":"金额单位是百万分之一元（micro_cny）。","properties":{"currency":{"type":"string"},"estimated_micro_cny":{"type":"integer"},"charged_micro_cny":{"type":"integer"},"reserved_micro_cny":{"type":"integer"}}},"media":{"anyOf":[{"type":"object","properties":{"status":{"type":"string"},"has_frame":{"type":"boolean"},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"成片保存截止时间，Unix 秒。"}}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"reason":{"type":"string"}}},{"type":"null"}],"description":"失败原因，未失败时为 null。"}}}},"responses":{"BadRequest":{"description":"请求内容有误，例如超出模型的上下文长度（CONTEXT_LIMIT_EXCEEDED）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CONTEXT_LIMIT_EXCEEDED","message":"对话内容超出模型可处理的长度。","request_id":"req_0123456789abcdef","retryable":false}}}}},"InvalidKey":{"description":"密钥缺失或无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_API_KEY","message":"网关 API 密钥无效。","request_id":"req_0123456789abcdef","retryable":false}}}}},"PaymentRequired":{"description":"余额不足（INSUFFICIENT_BALANCE）或达到密钥的消费上限（KEY_SPEND_LIMIT_REACHED），请到 /model 充值或调整上限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INSUFFICIENT_BALANCE","message":"余额不足，请充值后再试。","request_id":"req_0123456789abcdef","retryable":false}}}}},"ScopeDenied":{"description":"密钥没有调用该接口的权限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"SCOPE_DENIED","message":"当前密钥没有调用该接口的权限。","request_id":"req_0123456789abcdef","retryable":false}}}}},"RateLimited":{"description":"超出调用频率或每分钟 token 上限，请稍后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"请求过于频繁，请稍后重试。","request_id":"req_0123456789abcdef","retryable":true}}}}},"Unavailable":{"description":"服务暂不可用，可以稍后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"GATEWAY_TEMPORARILY_UNAVAILABLE","message":"网关服务暂不可用，请稍后重试。","request_id":"req_0123456789abcdef","retryable":true}}}}}}}}