API 端点

基础信息

项目	值
Base URL	`https://zivv.pro`
认证方式	`Authorization: Bearer sk-xxx` 或 `x-api-key: sk-xxx` 或 `x-goog-api-key: sk-xxx`
传输协议	HTTPS
内容类型	`application/json`

端点总览

协议 / 能力	方法与路径	说明
OpenAI Chat	`POST /v1/chat/completions`	OpenAI 兼容对话与流式输出
OpenAI Responses	`POST /v1/responses`	Codex、工具调用和 Responses 工作流
Anthropic Messages	`POST /v1/messages`	Claude 原生 Messages API
Anthropic Token 计数	`POST /v1/messages/count_tokens`	请求发送前估算 Messages 输入 Token
OpenAI 图片生成	`POST /v1/images/generations`	文生图与流式图片生成
OpenAI 图片编辑	`POST /v1/images/edits`	`multipart/form-data` 图片编辑
模型列表	`GET /v1/models`	OpenAI 兼容模型列表
Gemini 模型列表	`GET /v1beta/models`	Gemini 原生模型列表
Gemini 生成	`POST /v1beta/models/{model}:generateContent`	Gemini 非流式生成
Gemini 流式生成	`POST /v1beta/models/{model}:streamGenerateContent`	Gemini SSE 流式生成
视频生成（Synthesis 口径）	`POST /v1/services/aigc/video-generation/video-synthesis`	提交异步图生视频任务
异步任务（Synthesis 口径）	`GET /v1/tasks/{task_id}`	查询视频任务状态和结果
视频生成（Contents 口径）	`POST /api/v3/contents/generations/tasks`	提交异步多模态视频任务
异步任务（Contents 口径）	`GET /api/v3/contents/generations/tasks/{task_id}`	查询多模态视频任务状态和结果
健康检查	`GET /health`	无需认证的服务状态

各协议的 Base URL 和认证差异见协议与兼容性。模型、分组和价格以模型广场为准。

两套视频端点不通用

Synthesis 口径和 Contents 口径的请求体、任务查询路径和状态取值都不一样，不能互换。同一个视频模型只支持其中一套，用错端点会返回模型不可用或参数错误。不确定某个模型走哪一套时请联系管理员确认。

端点详情

健康检查

GET /health

无需认证。返回服务状态。

响应示例：

json

{
  "status": "ok"
}

模型列表

GET /v1/models

需要认证。返回当前可用的模型列表。

响应示例：

json

{
  "object": "list",
  "data": [
    {
      "id": "example-model-id",
      "object": "model",
      "owned_by": "zivv"
    },
    {
      "id": "example-image-model-id",
      "object": "model",
      "owned_by": "zivv"
    }
  ]
}

Chat Completions（OpenAI 格式）

POST /v1/chat/completions

兼容 OpenAI Chat Completions API。

请求体：

参数	类型	必填	说明
`model`	string	是	模型广场中的完整模型 ID
`messages`	array	是	消息数组
`stream`	boolean	否	是否流式输出，默认 `false`
`temperature`	number	否	温度参数，0-2
`top_p`	number	否	核采样参数
`max_tokens`	number	否	最大输出 token 数；可用上限取决于模型和当前网关限制

请求示例：

json

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false
}

响应示例：

json

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "YOUR_MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  }
}

Messages（Anthropic 格式）

POST /v1/messages

兼容 Anthropic Messages API。

请求头：

请求头	必填	说明
`x-api-key`	是	API Key
`anthropic-version`	否	API 版本，默认 `2023-06-01`
`Content-Type`	是	`application/json`

请求体：

参数	类型	必填	说明
`model`	string	是	模型 ID
`messages`	array	是	消息数组
`max_tokens`	number	是	最大输出 token 数；缺失时补默认值，超出模型上限时收敛
`stream`	boolean	否	是否流式输出
`temperature`	number	否	接受但不生效，转发前会剔除（当前模型代际已移除该参数，详见请求兼容性修正）

请求示例：

json

{
  "model": "YOUR_MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Hello!"}
  ]
}

响应示例：

json

{
  "id": "msg-xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "YOUR_MODEL_ID",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 12
  }
}

Messages Token 计数

POST /v1/messages/count_tokens

按 Anthropic Messages 请求格式预估输入 Token。适合在发送正式请求前评估上下文大小、预算和是否需要压缩历史消息。

认证头与 /v1/messages 相同：

http

x-api-key: sk-你的Key
anthropic-version: 2023-06-01
Content-Type: application/json

请求体可复用即将发送给 /v1/messages 的 model、system、messages 和工具定义：

json

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {"role": "user", "content": "请总结这段内容"}
  ]
}

响应包含估算的输入 Token 数。估算值用于请求前控制上下文，最终计费仍以实际模型响应和用量日志为准。

Responses（OpenAI Responses API）

POST /v1/responses

兼容 OpenAI Responses API（Codex CLI 使用此端点）。

请求体：

参数	类型	必填	说明
`model`	string	是	模型 ID
`input`	string/array	是	输入内容
`stream`	boolean	否	是否流式输出

图片生成（Images API）

POST /v1/images/generations

兼容 OpenAI Images API。请从模型广场复制当前可用的图片模型 ID；支持的尺寸、质量、流式能力和其他参数以目标模型为准。

请求体：

参数	类型	必填	说明
`model`	string	是	模型广场中的图片模型 ID
`prompt`	string	是	图片描述
`n`	integer	否	生成数量，默认 `1`
`size`	string	否	尺寸：`1024x1024`（默认）、`1024x1536`、`1536x1024`、`auto`
`quality`	string	否	质量：`auto`（默认）、`high`、`medium`、`low`
`background`	string	否	背景：`auto`（默认）、`transparent`、`opaque`
`output_format`	string	否	输出格式：`png`（默认）、`jpeg`、`webp`
`moderation`	string	否	审核级别：`auto`（默认）、`low`
`stream`	boolean	否	是否流式（SSE partial_images），默认 `false`

非流式请求示例：

json

{
  "model": "YOUR_IMAGE_MODEL_ID",
  "prompt": "a white cat sitting on a windowsill",
  "size": "1024x1024",
  "quality": "high",
  "n": 1
}

非流式响应示例：

json

{
  "data": [
    {
      "b64_json": "/9j/4AAQ...(base64 图片数据)...",
      "revised_prompt": "a white cat..."
    }
  ]
}

流式请求示例：

json

{
  "model": "YOUR_IMAGE_MODEL_ID",
  "prompt": "a cute puppy",
  "stream": true,
  "partial_images": 3
}

流式模式返回 SSE 事件流，包含 image_generation.partial_image（中间结果）和 image_generation.complete（最终图片），以 data: [DONE] 结束。

通过 Chat Completions 生成图片

当 model 为图片模型时，/v1/chat/completions 端点会自动识别并转换为图片生成请求，无需修改客户端配置。

支持的额外参数（直接放在 chat 请求体中）：

参数	类型	说明
`size`	string	图片尺寸
`quality`	string	图片质量
`background`	string	背景模式
`output_format`	string	输出格式
`moderation`	string	审核级别
`n`	integer	生成数量

请求示例（Cherry Studio / ChatBox 等客户端）：

json

{
  "model": "YOUR_IMAGE_MODEL_ID",
  "messages": [
    {"role": "user", "content": "画一只白猫坐在窗台上"}
  ],
  "size": "1024x1024",
  "quality": "high",
  "stream": true
}

图片将以 Markdown 格式 ![image](data:image/png;base64,...) 返回在 content 中，大多数客户端可直接渲染。

注意事项：

prompt 自动提取自最后一条 user 消息的文本内容
system 消息会被忽略（图片模型不支持 system prompt）
stream=true 仍然可用，响应会包装成 chat completion SSE 格式
temperature、top_p、max_tokens 等文本模型参数会被忽略

多图参考与图层拆分（部分模型）

部分图片模型在标准 Images API 之上支持多图参考和图层拆分，通过下列额外参数使用：

参数	类型	说明
`image`	string / string[]	参考图。单张传字符串，多张传字符串数组，元素为公网 URL 或 Base64
`layer_decomposition`	boolean	图层拆分。一次返回 1 张底图加最多 16 个图层，各图层单价为普通图片生成的一半
`size`	string	`1K`、`2K` 或具体的 `宽x高`。实际计费档位以响应中每张图返回的 `size` 为准，不看请求值

请求示例（多图参考）：

json

{
  "model": "YOUR_IMAGE_MODEL_ID",
  "prompt": "把这两张参考图的风格融合成一张海报",
  "image": [
    "https://example.com/ref1.png",
    "https://example.com/ref2.png"
  ],
  "size": "2K"
}

响应示例：

json

{
  "data": [
    { "url": "https://.../base.png", "size": "2048x2048" },
    { "url": "https://.../layer1.png", "size": "1273x265" }
  ],
  "usage": {
    "input_images": 2,
    "generated_images": 2
  }
}

注意事项：

这类模型不支持 stream。流式响应拿不到完整的 usage.input_images 和每张图的 size，按张计费无法结算，带 stream: true 的请求会被拒绝
参考图第一张免费，第二张起按张计费
输出图逐张定档计价，不按最大尺寸一刀切 —— 图层拆分返回的各图层尺寸参差不齐，逐张算更接近实际
若响应中某张图缺少 size 字段导致无法定档，请求会返回错误而不是按猜测的档位计费
该模型的档位价格未配置完整时，请求在发出之前就会被拒，不会先生成图再报错

图片编辑（Images Edits API）

POST /v1/images/edits

兼容 OpenAI Images Edits API，使用 multipart/form-data 上传输入图片。基础字段：

参数	类型	必填	说明
`model`	string	是	支持图片编辑的模型 ID
`image`	file	是	要编辑的源图片
`prompt`	string	是	编辑要求
`size`	string	否	输出尺寸，模型支持范围以模型广场为准
`quality`	string	否	输出质量
`n`	integer	否	输出数量

bash

curl https://zivv.pro/v1/images/edits \
  -H "Authorization: Bearer sk-你的Key" \
  -F "model=YOUR_IMAGE_MODEL" \
  -F "prompt=把背景改成夜晚城市" \
  -F "[email protected]" \
  -F "size=auto"

渠道兼容性

图片编辑需要支持 /v1/images/edits 的模型和上游渠道。若模型只支持 Responses API 图像工具，请改用 /v1/responses；具体能力以模型广场和请求错误为准。

视频生成（图生视频）

POST /v1/services/aigc/video-generation/video-synthesis

异步图生视频接口，支持 happyhorse-1.1-i2v 等图生视频模型。提交任务返回 task_id，再轮询 GET /v1/tasks/{task_id} 获取结果。

请求头：

请求头	必填	说明
`Authorization`	是	`Bearer sk-xxx`
`X-DashScope-Async`	是	异步调用固定为 `enable`
`Content-Type`	是	`application/json`

请求体：

参数	类型	必填	说明
`model`	string	是	图生视频模型，如 `happyhorse-1.1-i2v`
`input.prompt`	string	是	视频内容描述
`input.img_url`	string	是	首帧图片，公网 URL 或 Base64
`input.audio_url`	string	否	唇形同步音频，公网 URL
`parameters.resolution`	string	否	分辨率：`720P`、`1080P`
`parameters.duration`	integer	否	时长，3–15 的整数秒
`parameters.prompt_extend`	boolean	否	是否开启提示词改写

请求示例：

json

{
  "model": "happyhorse-1.1-i2v",
  "input": {
    "prompt": "镜头从海龟下方缓缓上移，海龟悠然游动，腹部细节清晰可见。",
    "img_url": "https://example.com/first_frame.png"
  },
  "parameters": {
    "resolution": "1080P",
    "duration": 10,
    "prompt_extend": true
  }
}

响应示例：

json

{
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "output": {
    "task_id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "task_status": "PENDING"
  }
}

输入约束：

首帧图片：1 张，公网 URL（推荐）或 Base64（data:<MIME>;base64,<data>），支持 JPEG/PNG/BMP/WEBP
音频：1 个，仅公网 HTTP(S) URL，wav/mp3，3–30 秒，≤15MB

计费： 按成功生成视频的秒数计费，调用失败或处理出错不计费。单价见模型广场。

注意

异步接口必须携带请求头 X-DashScope-Async: enable，否则任务无法提交。输出视频 URL 有效期 24 小时，请及时转存。

查询异步任务

GET /v1/tasks/{task_id}

查询异步任务（如视频生成）的状态与结果。需要认证。

响应示例：

json

{
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "output": {
    "task_id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "task_status": "SUCCEEDED",
    "video_url": "https://.../result.mp4"
  }
}

task_status 取值：PENDING、RUNNING、SUCCEEDED、FAILED。

多模态视频生成（Contents 口径）

POST /api/v3/contents/generations/tasks

异步视频生成接口，支持在一次请求里同时给出文本、参考图、参考视频和参考音频。提交任务返回 id，再轮询 GET /api/v3/contents/generations/tasks/{task_id} 获取结果。

与 Synthesis 口径的区别：内容放在扁平的 content 数组里（不是 input / parameters 两层），任务查询走各自的路径，状态取值为小写。

请求头：

请求头	必填	说明
`Authorization`	是	`Bearer sk-xxx`
`Content-Type`	是	`application/json`

不需要 X-DashScope-Async，那是 Synthesis 口径的要求。

请求体：

参数	类型	必填	说明
`model`	string	是	模型广场中的视频模型 ID
`content`	array	二选一	多模态内容数组，见下表
`prompt`	string	二选一	纯文本简写，与 `content` 互斥，同时传返回 `400`
`images`	string[]	否	参考图 URL 简写，配合 `prompt` 使用
`resolution`	string	否	输出分辨率 `480P` / `720P`（默认）/ `1080P` / `4K`，也接受 `480`、`720`、`1080`、`2160P`
`ratio`	string	否	画面比例，如 `16:9`
`duration`	integer	否	时长秒数，取值 4–15
`frames`	integer	否	帧数（固定 24fps），与 `duration` 表达同一个量
`seed`	integer	否	`-1` 或 0–2147483647

content 数组元素：

`type`	内容字段	说明
`text`	`text`	提示词，不可为空字符串
`image_url`	`image_url.url`	参考图
`video_url`	`video_url.url`	参考视频
`audio_url`	`audio_url.url`	参考音频

每个元素可附带 role（如 reference_image、reference_video、reference_audio），原样转发给上游。媒体地址必须是公网 HTTP(S) URL 或 data:<MIME>;base64,<data>。

请求示例：

json

{
  "model": "YOUR_VIDEO_MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "第一人称视角，手持一杯分层果茶举到镜头前，杯身标签清晰可见。"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/ref1.jpg" },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/ref.mp4" },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": { "url": "https://example.com/bgm.mp3" },
      "role": "reference_audio"
    }
  ],
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 11
}

响应示例：

json

{
  "id": "cgt-20260904025813-xxxxx"
}

参数约束：

duration 必须在 4–15 秒之间，超出返回 400
frames 不是 24 的整数倍时按整秒向上取整（例如 250 视为 11 秒）
提示词里的 --resolution / --duration / --frames 简写与顶层同名字段取值必须一致；冲突时返回 400 而不是取其中一个。多个 text 元素之间同名简写冲突同样返回 400
分辨率取值无法识别时返回 400，不会按默认档处理

不支持 tools

携带 tools（含联网搜索）的请求会被拒绝。这类能力在上游按调用次数独立计价，与视频用量分开结算，本网关没有对应计费维度；静默丢弃会让你以为开启了实际却没有，所以直接返回 400。

错误格式：

json

{
  "error": {
    "code": "InvalidParameter",
    "message": "duration must be between 4 and 15 seconds"
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

常见 code：InvalidParameter（参数错误）、PermissionDenied（Key 模型白名单不含该模型）、ModelNotFound（模型或分组不可用）、QuotaExceeded（余额或额度不足）、InvalidTask（任务不存在或不属于当前用户）。

计费： 按 Token 计费，用量取上游返回的 usage.total_tokens，单价随输出分辨率和是否包含参考视频两个维度变化。创建任务时按请求参数锁定单价，只有 succeeded 的任务计费。详见计费说明。

查询多模态视频任务（Contents 口径）

GET /api/v3/contents/generations/tasks/{task_id}

需要认证。只能查询当前用户自己提交的任务，查别人的任务返回 404。

响应示例：

json

{
  "id": "cgt-20260904025813-xxxxx",
  "model": "YOUR_VIDEO_MODEL_ID",
  "status": "succeeded",
  "content": {
    "video_url": "https://.../result.mp4"
  },
  "usage": {
    "completion_tokens": 411300,
    "total_tokens": 411300
  }
}

status 取值（小写，与 Synthesis 口径的大写不同）：queued、running、succeeded、failed。

注意

输出视频 URL 是带签名的临时地址，有效期 24 小时，请及时转存
任务提交成功后即进入上游处理流程。客户端停止轮询不代表任务取消，网关后台仍会跟进状态并完成结算
任务超过 24 小时未进入终态会被标记过期并退还预扣金额

Gemini generateContent

POST /v1beta/models/{model}:generateContent

兼容 Gemini 原生 API，非流式生成。

请求头：

请求头	必填	说明
`x-goog-api-key`	是	API Key
`Content-Type`	是	`application/json`

请求体：

参数	类型	必填	说明
`contents`	array	是	内容数组
`generationConfig`	object	否	生成配置（temperature、maxOutputTokens 等）

请求示例：

json

{
  "contents": [
    {
      "parts": [{"text": "Hello!"}]
    }
  ]
}

响应示例：

json

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Hello! How can I help you?"}]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 8
  }
}

Gemini streamGenerateContent

POST /v1beta/models/{model}:streamGenerateContent

兼容 Gemini 原生 API，流式生成。请求格式与 generateContent 相同，响应以 SSE 流返回。

Gemini 生图（原生协议）

POST /v1beta/models/{model}:generateContent

复用 generateContent 端点生图：使用模型广场当前提供的 Gemini 图片模型。图片以 inlineData（Base64）返回在响应的 parts 中。

generationConfig.responseModalities 可以不传 —— 网关识别到生图模型时会自动补上 Image；如果你显式传了 ["Text"]，网关会追加成 ["Text", "Image"]。已经声明过 Image 的请求原样转发。

请求体：

参数	类型	必填	说明
`contents`	array	是	内容数组；文生图只传 `text`，图生图额外传 `inlineData`（输入图片）
`generationConfig.responseModalities`	array	否	输出模态，不传则由网关补成 `["Image"]`；显式声明通常为 `["Text", "Image"]`
`generationConfig.imageConfig.aspectRatio`	string	否	宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4` 等
`generationConfig.imageConfig.imageSize`	string	否	分辨率：`1K`（默认）、`2K`、`4K`
`generationConfig.candidateCount`	integer	否	生成数量，默认 `1`
`generationConfig.seed`	integer	否	随机种子，固定可复现结果

请求示例：

json

{
  "contents": [
    { "parts": [{"text": "画一只戴墨镜的柯基，赛博朋克风格，霓虹灯背景"}] }
  ],
  "generationConfig": {
    "responseModalities": ["Text", "Image"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "2K"
    },
    "candidateCount": 1,
    "seed": 12345
  }
}

响应示例：

json

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgo...(base64 图片数据)..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

SDK 用法

Gemini 原生协议生图/图生图的 curl 与 SDK 完整示例见 Gemini 原生协议使用。

认证方式

Zivv API 支持三种认证方式，任选其一：

Bearer Token（OpenAI 风格）

Authorization: Bearer sk-你的Key

API Key Header（Anthropic 风格）

x-api-key: sk-你的Key

Google API Key Header（Gemini 风格）

x-goog-api-key: sk-你的Key

速率限制

当请求过于频繁时，API 会返回 429 Too Many Requests。建议：

控制请求频率，避免短时间内大量并发
收到 429 后，等待 Retry-After header 指示的时间后重试

API 端点 ​

基础信息 ​

端点总览 ​

端点详情 ​

健康检查 ​

模型列表 ​

Chat Completions（OpenAI 格式） ​

Messages（Anthropic 格式） ​

Messages Token 计数 ​

Responses（OpenAI Responses API） ​

图片生成（Images API） ​

图片编辑（Images Edits API） ​

视频生成（图生视频） ​

查询异步任务 ​

多模态视频生成（Contents 口径） ​

查询多模态视频任务（Contents 口径） ​

Gemini generateContent ​

Gemini streamGenerateContent ​

Gemini 生图（原生协议） ​

认证方式 ​

Bearer Token（OpenAI 风格） ​

API Key Header（Anthropic 风格） ​

Google API Key Header（Gemini 风格） ​

速率限制 ​

API 端点

基础信息

端点总览

端点详情

健康检查

模型列表

Chat Completions（OpenAI 格式）

Messages（Anthropic 格式）

Messages Token 计数

Responses（OpenAI Responses API）

图片生成（Images API）

图片编辑（Images Edits API）

视频生成（图生视频）

查询异步任务

多模态视频生成（Contents 口径）

查询多模态视频任务（Contents 口径）

Gemini generateContent

Gemini streamGenerateContent

Gemini 生图（原生协议）

认证方式

Bearer Token（OpenAI 风格）

API Key Header（Anthropic 风格）

Google API Key Header（Gemini 风格）

速率限制