Sysrv — API 文档

GET /v1/models ▾

描述

列出所有可用模型（图像 + 视频）。

请求头

Authorization: Bearer <api_key>
Content-Type: application/json

响应

{
  "object": "list",
  "data": [
    { "id": "gpt-image-2", "object": "model", "owned_by": "openai", "description": "..." },
    { "id": "sora2", "object": "model", "owned_by": "openai", "description": "..." }
  ]
}

示例

curl -X GET https://sysrv.net/v1/models \ -H "Authorization: Bearer YOUR_API_KEY"

POST /v1/images/generations ▾

描述

OpenAI 兼容的图像生成接口。支持文生图和图生图（通过 images 或 image_url 参数传入参考图）。

请求头

Authorization: Bearer <api_key>
Content-Type: application/json  (或 multipart/form-data)

请求体 (JSON)

参数	类型	必填	说明
prompt	string	是	图像描述，最长 32000 字符
model	string	否	模型 ID，如 `gpt-image-2`
n	integer	否	只支持 `1`
size	string	否	如 `1024x1024` / `1536x1024` / `1024x1536` / `2048x2048` / `2048x1152` / `3840x2160` / `2160x3840` 等；默认由模型决定
quality	string	否	`low` / `medium` / `high` ；仅 `gpt-image-2` 系列有效
response_format	string	否	`url`（默认） / `b64_json` / `privacy_url`
aspect_ratio	string	否	兼容参数，默认 `16:9`
image_url	string	否	参考图 URL（图生图）
images	array	否	参考图列表，每项为 URL 或 `{image_url:"..."}`
stream	boolean	否	设为 `true` 启用 SSE 流式响应

响应

{
  "created": 1719000000,
  "model": "gpt-image-2",
  "data": [{ "url": "https://sysrv.net/cache/generated/abc123.png" }]
}

示例

curl -X POST https://sysrv.net/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A cat", "model": "gpt-image-2", "size": "9:16" }'

POST /v1/images/edits ▾

描述

OpenAI 兼容的图像编辑（图生图）接口。必须提供参考图片。

请求体

支持 application/json 和 multipart/form-data。参数与 /v1/images/generations 一致，但必须通过 images 或 image 字段传入至少一张参考图。

示例

curl -X POST https://sysrv.net/v1/images/edits \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "prompt=Add a dragon in the sky" \ -F "image=@/path/to/photo.jpg" \ -F "model=gpt-image-2"

POST /v1/videos ▾

描述

创建视频生成任务。支持 Veo 3.1 系列模型（veo-3.1、veo-3.1-fast、omni-flash）。可通过 input_reference 或 image_url 传入首帧参考图。

提示：如需使用首尾帧图生视频，请改用 NewAPI 兼容接口（/v1/video/generations），支持 metadata.image（首帧）和 metadata.lastFrame（尾帧）。

请求体

参数	类型	必填	说明
prompt	string	是	视频描述
model	string	否	模型ID，如 `veo-3.1-fast` / `veo-3.1` / `omni-flash`
aspect_ratio	string	否	`16:9` 或 `9:16`
durationSeconds	integer	否	时长（秒），Veo31 支持 8s
resolution	string	否	`720p`（默认）或 `1080p`
input_reference	string	否	首帧参考图 URL（图生视频）
generate_audio	boolean	否	是否生成音频，默认 `true`
negative_prompt	string	否	负向提示词
stream	boolean	否	设为 `true` 启用 SSE 流式响应

响应

{
  "id": "video_abc123",
  "object": "video",
  "model": "veo-3.1-fast",
  "status": "completed",
  "progress": 100,
  "created_at": 1719000000,
  "size": "1280x720",
  "seconds": "8",
  "prompt": "...",
  "url": "https://sysrv.net/cache/generated/abc.mp4",
  "content_url": "https://sysrv.net/cache/generated/abc.mp4"
}

示例

curl -X POST https://sysrv.net/v1/videos \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A cat walking on a sunny beach", "model": "veo-3.1-fast", "aspect_ratio": "16:9", }'

GET /v1beta/models ▾

描述

列出所有可用模型（图像 + 视频）。

认证

Authorization: Bearer <api_key>
X-Goog-Api-Key: <api_key>    (也支持)

响应

{
  "object": "list",
  "data": [
    { "id": "nano-banana-pro", "object": "model", "owned_by": "gemini", "description": "..." },
    { "id": "nano-banana-2", "object": "model", "owned_by": "gemini", "description": "..." }
  ]
}

示例

curl -X GET https://sysrv.net/v1beta/models \ -H "Authorization: Bearer YOUR_API_KEY"

POST /v1beta/models/{model}:generateContent ▾

描述

Gemini 兼容的图像生成。

请求体

参数	类型	说明
contents	array/object	Gemini 格式的 contents，支持 text 和 inline_data
generationConfig.imageConfig.aspectRatio	string	宽高比，如 `16:9`
generationConfig.imageConfig.imageSize	string	分辨率，如 `1K`、`2K`、`4K`
response_format	string	`url`（默认）或 `b64_json`

示例

curl -X POST https://sysrv.net/v1beta/models/gemini-3-pro-image-preview:generateContent \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contents": [{ "parts": [{ "text": "A beautiful sunset over mountains" }] }], "generationConfig": { "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" } } }'

POST /v1beta/models/{model}:streamGenerateContent ▾

描述

Gemini 兼容的流式图像生成。返回 SSE 事件流，包含 progress 事件和最终的 result 事件。

请求体

与 :generateContent 一致。

SSE 事件流

event: progress
data: {"status":"in_progress","progress":0,"model":"nano-banana-2"}

event: progress
data: {"status":"in_progress","progress":45,"upstream_job_id":"..."}

event: result
data: {"candidates":[{...}]}

data: [DONE]

示例

curl -X POST https://sysrv.net/v1beta/models/gemini-3-pro-image-preview:streamGenerateContent \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contents": [{ "parts": [{ "text": "A beautiful sunset over mountains" }] }], "generationConfig": { "imageConfig": { "aspectRatio": "16:9" } } }'

POST /v1beta/models/{model}:predictLongRunning ▾

描述

（异步模式）。通过 instances[0].prompt 传入提示词，parameters 传视频参数。支持首帧（instances[0].image）和首尾帧（instances[0].image + instances[0].lastFrame）图生视频。

工作流程：POST 请求返回 {"name": "<operationId>", "done": false}，然后通过 GET /v1beta/operations/{name} 轮询直到 done: true。

Gemini 兼容的视频生成。通过 instances[0].prompt 传入提示词，parameters 传视频参数。支持首帧（instances[0].image）和首尾帧（instances[0].image + instances[0].lastFrame）图生视频。

支持模型

Gemini 模型名	对应内部模型	首帧	首尾帧
veo-3.1-generate-preview	veo-3.1	✅	✅
veo-3.1-fast-generate-preview	veo-3.1-fast	✅	✅
veo-3.1-lite-generate-preview	omni-flash	✅	❌

请求体

{
  "instances": [{
    "prompt": "A cat walking on a sunny beach",
    "image": { "inlineData": { "mimeType": "image/jpeg", "data": "<base64>" } },
    "lastFrame": { "inlineData": { "mimeType": "image/jpeg", "data": "<base64>" } }
  }],
  "parameters": {
    "aspectRatio": "16:9",
    "durationSeconds": 4,
    "resolution": "720p",
    "negativePrompt": "blurry"
  }
}

（异步创建）

{
  "name": "abc123def4567890",
  "done": false
}

返回的 name 是 operation ID，用于轮询 GET /v1beta/operations/{name}。

轮询结果（完成时）

{
  "name": "abc123def4567890",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/...",
    "generatedVideos": [
      { "video": { "uri": "https://..." }, "mimeType": "video/mp4" }
    ] "generatedSamples": [{ "video": { "uri": "https://..." } }]
    }
  }
}

示例

# 步骤 1: 创建视频生成任务
curl -X POST https://sysrv.net/v1beta/models/veo-3.1-fast-generate-preview:predictLongRunning \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [{
      "prompt": "A cat walking on a sunny beach"
    }],
    "parameters": {
      "aspectRatio": "16:9",
      "durationSeconds": 8,
      "resolution": "720p"
    }
  }'
# 返回: {"name": "abc123def4567890", "done": false}

# 步骤 2: 轮询操作结果
curl -X GET https://sysrv.net/v1beta/operations/abc123def4567890 \
  -H "Authorization: Bearer YOUR_API_KEY"
# 返回: {"name": "abc123def4567890", "done": true, "response": {...}}
            

GET /v1beta/operations/{operation_id} ▾

描述

轮询 Gemini 视频生成的操作结果。传入 :predictLongRunning 返回的 name 字段值。

响应（进行中）

{
  "name": "abc123def4567890",
  "done": false
}

响应（完成）

{
  "name": "abc123def4567890",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/...",
    "generatedVideos": [
      { "video": { "uri": "https://..." }, "mimeType": "video/mp4" }
    ]
  }
}

响应（失败）

{
  "name": "abc123def4567890",
  "done": true,
  "error": { "code": 500, "message": "..." }
}

查询 Gemini 视频生成的操作结果。

示例

curl -X GET https://sysrv.net/v1beta/operations/abc123 \ -H "Authorization: Bearer YOUR_API_KEY"

POST /v1/video/generations ▾

描述

创建视频生成任务（异步模式）。支持文生视频、首帧图生视频、首尾帧图生视频。图片通过 inlineData 对象传入，data 字段支持 base64、HTTP(S) URL 和 data URI。

请求头

Authorization: Bearer <api_key>
Content-Type: application/json

请求体

参数	类型	必填	说明
model	string	是	模型 ID，见下方支持模型一览
prompt	string	是	视频描述文本
metadata	object	否	视频参数及图片输入，见下方详解

metadata 参数详解

参数	类型	必填	说明
aspectRatio	string	否	`16:9`（默认）或 `9:16`
durationSeconds	integer	否	视频时长（秒），默认 8s
resolution	string	否	`720p`（默认）或 `1080p`
negativePrompt	string	否	负向提示词
image	object / string	否	首帧图片。推荐使用 `{"inlineData": {"mimeType": "...", "data": "..."}}`，`data` 字段支持纯 base64、HTTP(S) URL 或 data URI；也可直接传字符串
lastFrame	object / string	否	尾帧图片。格式同 `image`。仅 veo-3.1 / veo-3.1-fast 支持

图片输入格式说明

首帧和尾帧图片统一通过 inlineData 对象传入，data 字段支持以下三种内容：

// 标准格式：inlineData 对象
"image": {
  "inlineData": {
    "mimeType": "image/jpeg",
    "data": "..."
  }
}

// data 字段可为：
//   1. 纯 base64 字符串
//      "/9j/4AAQSkZJRgABAQAAAQABAAD..."
//   2. HTTP(S) URL
//      "https://example.com/frame.jpg"
//   3. data URI
//      "data:image/png;base64,iVBORw0KGgo..."

响应（异步创建）

{
  "id": "task_abc123",
  "object": "video.generation",
  "model": "veo-3.1-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1719000000
}

示例

文生视频

curl -X POST https://sysrv.net/v1/video/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "veo-3.1-fast", "prompt": "A cinematic drone shot flying over a misty mountain lake at sunrise", "metadata": { "aspectRatio": "16:9" } }'

首帧图生视频

# 首帧 base64 输入 curl -X POST https://sysrv.net/v1/video/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "veo-3.1-fast", "prompt": "缓慢漂浮起来，在透明和实体之间切换，光影质感", "metadata": { "image": { "inlineData": { "mimeType": "image/png", "data": "iVBORw0KGgoAAAANSUhEUgAA..." } }, "aspectRatio": "9:16" } }'

首尾帧图生视频

# 首尾帧 base64 输入 curl -X POST https://sysrv.net/v1/video/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "veo-3.1-fast", "prompt": "首帧平视推进到店铺内，和尾帧无缝衔接", "metadata": { "image": { "inlineData": { "mimeType": "image/jpeg", "data": "/9j/4AAQSkZJRg..." } }, "lastFrame": { "inlineData": { "mimeType": "image/jpeg", "data": "/9j/4AAQSkZJRg..." } }, "aspectRatio": "9:16" } }'

GET /v1/video/generations/{task_id} ▾

描述

轮询视频生成任务状态。任务完成后返回视频下载 URL。

响应（进行中）

{
  "id": "task_abc123",
  "object": "video.generation",
  "model": "veo-3.1-fast",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1719000000
}

响应（完成）

{
  "id": "task_abc123",
  "object": "video.generation",
  "model": "veo-3.1-fast",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1719000000,
  "completed_at": 1719000120,
  "data": {
    "url": "https://sysrv.net/cache/generated/abc.mp4"
  }
}

响应（失败）

{
  "id": "task_abc123",
  "status": "failed",
  "error": {
    "message": "Generation failed: content moderation",
    "code": "content_moderation"
  }
}

示例

curl -X GET https://sysrv.net/v1/video/generations/task_abc123 \ -H "Authorization: Bearer YOUR_API_KEY"

🎬 NewAPI 视频模型一览

模型 ID	首帧	首尾帧	宽高比	时长	分辨率
veo-3.1-fast	✅	✅	16:9 / 9:16	8s	1080p
veo-3.1	✅	✅	16:9 / 9:16	8s	1080p
omni-flash	✅	❌	16:9 / 9:16	8s	720p

图片输入格式：首帧通过 metadata.image 传入，尾帧通过 metadata.lastFrame 传入。推荐使用 {"inlineData": {"mimeType": "...", "data": "..."}} 对象格式，data 字段支持 纯 base64、HTTP(S) URL 和 data URI；也可直接传字符串（等价于 data 字段）。

⚠️ 错误码速查

HTTP 状态码	含义
400	请求参数错误（无效模型、缺少 prompt、不支持的宽高比等）
401	API Key 无效或未提供
429	Token 配额耗尽
451	内容审核拦截（触发 content_review_keywords）或上游返回 image_unsafe
500	服务器内部错误
503	上游服务临时不可用 / 无可用 Token

OpenAI 兼容接口

描述

请求头

响应

示例

描述

请求头

请求体 (JSON)

响应

示例

描述

请求体

示例

描述

请求体

响应

示例

Gemini 兼容接口

描述

认证

响应

示例

描述

请求体

示例

描述

请求体

SSE 事件流

示例

描述

支持模型

请求体

轮询结果（完成时）

示例

描述

响应（进行中）

响应（完成）

响应（失败）

示例

NewAPI 兼容接口

描述

请求头

请求体

metadata 参数详解

图片输入格式说明

响应（异步创建）

示例

文生视频

首帧图生视频

首尾帧图生视频

描述

响应（进行中）

响应（完成）

响应（失败）

示例

🎬 NewAPI 视频模型一览

⚠️ 错误码速查