API 接入说明 — ZipTop AI

GGEMINI2 个可用模型

Gemini 对接文档

原生 Gemini 模型使用 /v1beta/models/{model}:generateContent；异步提交后请读取响应中的完整 name，并使用 GET /v1beta/{name} 查询。当前 ZipTop 图片任务返回 operations/imgtask_...，因此实际查询为 GET /v1beta/operations/imgtask_...；这是当前资源类型示例，不要由 task_id 固定拼接路径。实际可用路径以模型表为准。

认证方式Authorization: Bearer YOUR_API_KEY模型调用均使用 API 密钥认证，请在请求头中绑定对应平台分组。

当前支持模型

模型	类型	推荐接口	说明
gemini-3.6-flash	文本	`/v1/chat/completions`	当前支持
gemini-3.1-flash-image-preview	图片	`/v1beta/models/{model}:generateContent`	当前支持

MMIDJOURNEY1 个可用模型

MidJourney 对接文档

OpenAI 兼容模型使用 /v1/chat/completions 或 /v1/images/generations。实际可用路径以模型表为准。

认证方式Authorization: Bearer YOUR_API_KEY模型调用均使用 API 密钥认证，请在请求头中绑定对应平台分组。

当前支持模型

模型	类型	推荐接口	说明
mj_imagine	图片	`/mj/submit/imagine`	当前支持

OOPENAI3 个可用模型

OpenAI 对接文档

OpenAI 兼容模型使用 /v1/chat/completions 或 /v1/images/generations。实际可用路径以模型表为准。

认证方式Authorization: Bearer YOUR_API_KEY模型调用均使用 API 密钥认证，请在请求头中绑定对应平台分组。

当前支持模型

模型	类型	推荐接口	说明
gpt-image-2	图片	`/v1/images/generations`	当前支持
gpt-5.6-sol	文本	`/v1/chat/completions`	当前支持
gpt-image-2	图片	`/v1/images/generations`	当前支持

SSUNO1 个可用模型

Suno 对接文档

OpenAI 兼容模型使用 /v1/chat/completions 或 /v1/images/generations。实际可用路径以模型表为准。

认证方式Authorization: Bearer YOUR_API_KEY模型调用均使用 API 密钥认证，请在请求头中绑定对应平台分组。

当前支持模型

模型	类型	推荐接口	说明
suno_music	语音	`/suno/submit/music`	当前支持

POST/v1/chat/completions

Chat Completions

OpenAI 兼容聊天接口，适合 ChatBox、OpenCat、LangChain、OpenAI SDK 等客户端。

参数

`model` *	模型 ID。请从当前平台模型列表中选择。
`messages` *	OpenAI messages 数组，包含 role 和 content。
`stream`	是否流式返回。当前不支持 `true`，传入后返回 400。
`temperature`	采样温度，是否支持取决于上游模型。
`max_tokens`	最大输出 token；具体上限取决于模型。

认证：Authorization: Bearer <API_KEY>

请求示例

curl YOUR_BASE_URL/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_TEXT_MODEL",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'

响应示例

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "..."},
    "finish_reason": "stop"
  }]
}

POST/v1/images/generations

OpenAI 兼容图片接口

适用于 OpenAI 兼容图片模型。原生 Gemini 图片模型请使用下方的 Gemini generateContent 异步接口，不要使用本接口。

参数

`model` *	图片模型 ID。
`prompt` *	图片生成提示词。
`resolution`	分辨率，必须符合模型能力配置。
`ratio` / `size`	比例或尺寸，是否支持取决于模型。
`quality`、`style`、`n`	可选图片参数，不保证所有模型通用。

认证：Authorization: Bearer <API_KEY>

请求示例

curl YOUR_BASE_URL/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL",
    "prompt": "一座被晨雾环绕的山谷"
  }'

响应示例

{
  "created": 1710000000,
  "data": [{"url": "IMAGE_URL_FROM_UPSTREAM"}]
}

POST/v1beta/models/{model}:generateContent

原生 Gemini generateContent

文本模型同步返回 Gemini 原生响应；图片模型在中转站本地异步处理。提交成功后以完整的 name 作为任务标识，并按 GET /v1beta/{name} 查询，不要按 OpenAI 的 data[0].url 解析提交响应，也不要从 task_id 固定拼接 /operations/。

认证与流程

`contents` *	Gemini 原生 contents 数组。
`generationConfig`	生成配置；图片比例放在 `imageConfig.aspectRatio`。
图片提交	返回 `202` 和完整的 `name`（同时保留 `id`/`task_id` 兼容字段），不要按 OpenAI 的 `data[0].url` 解析提交响应。
图片轮询	读取返回的完整 `name`，只使用 `GET /v1beta/{name}` 查询，并携带相同的 Bearer API Key。
通用规则	`name=operations/abc123` 时查询 `GET /v1beta/operations/abc123`；若服务返回 `batches/abc123`，则查询 `GET /v1beta/batches/abc123`。调用方不要假定资源类型。
下家配置	如果下家配置需要填写固定状态路径，可填写 `/v1beta/operations`，并使用提交响应中的 `id` 以 `?job_id=...` 查询；例如 `/v1beta/operations?job_id=imgtask_xxx`。

认证：Authorization: Bearer <API_KEY>

请求示例

curl YOUR_BASE_URL/v1beta/models/YOUR_GEMINI_MODEL:generateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "一座被晨雾环绕的山谷"}]}]
  }'

图片提交响应

{
  "name": "operations/imgtask_xxx",
  "id": "imgtask_xxx",
  "task_id": "imgtask_xxx",
  "done": false,
  "status": "queued"
}

通用图片轮询地址

GET YOUR_BASE_URL/v1beta/{name}

# 使用本次响应中的 name：
GET YOUR_BASE_URL/v1beta/operations/imgtask_xxx

POST/mj/submit/imagine

MidJourney 专用中转

MidJourney 不使用 OpenAI 图片接口。首次请求提交 imagine 任务；中转站会根据后台配置的结果路径（例如 /mj/task/{id}/fetch）获取图片，并返回本站公网图片地址和 U1–U4 按钮参数。

提交与 U1–U4 操作

`botType`	通常填写 `MID_JOURNEY`。
`prompt` *	提示词，可包含 `--ar`、`--v`、`--s`、`--c`、`--q`、`--no`。
U1–U4	调用 `POST /mj/submit/action`，提交上一次返回的 `customId` 和 `taskId`。

认证：Authorization: Bearer <API_KEY>

提交示例

curl YOUR_BASE_URL/mj/submit/imagine \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "botType": "MID_JOURNEY",
    "prompt": "a cinematic mountain lake --ar 16:9 --v 7"
  }'

U1–U4 示例

POST YOUR_BASE_URL/mj/submit/action
{
  "customId": "MJ::JOB::upsample::1::...",
  "taskId": "上一次返回的任务 ID"
}

POST/suno/submit/music

Suno 专用中转

Suno 是异步任务接口。提交后返回本站任务 ID，再调用 GET /suno/fetch/{task_id} 轮询；完成后会返回两个音频的本站公网 HTTPS 地址。

提交与轮询

`gpt_description_prompt`	音乐描述或歌词提示词。
`make_instrumental`	是否生成纯音乐。
`mv`	Suno 上游版本，例如 `chirp-crow`。
结果	`data.data` 中通常包含两个音频项目，每个项目有 `audio_url` 和 `media_urls`。

认证：Authorization: Bearer <API_KEY>

提交示例

curl YOUR_BASE_URL/suno/submit/music \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gpt_description_prompt": "轻快的电子流行音乐",
    "make_instrumental": true,
    "mv": "chirp-crow"
  }'

轮询示例

GET YOUR_BASE_URL/suno/fetch/{task_id}

完成后：
{
  "data": {
    "status": "SUCCESS",
    "data": [
      {"audio_url": "https://www.ziptop-ai.com/api/uploads/audio-results/...mp3"},
      {"audio_url": "https://www.ziptop-ai.com/api/uploads/audio-results/...mp3"}
    ]
  }
}

错误响应

错误通常包含统一的 error.message、error.type、error.param 和 error.code 字段。常见状态码包括 400、401、403、404、422、429 和 502。

返回首页