给普通用户和二次中转用户的接入手册

按本手册可接入文本、图片、视频和音频能力。不同能力应使用对应 endpoint，并保留原始字段名。

服务地址

项目	值
首选 Base URL	`https://ai.silicogrove.com/v1`
备用 Base URL	`https://api.silicogrove.com/v1`，首选域名不可用时切换
认证	`Authorization: Bearer YOUR_API_KEY`
JSON 请求	`Content-Type: application/json`
文件上传	`multipart/form-data`

阅读顺序

从快速接入创建 Key、查询模型并完成最小请求。
从模型与权限确认可使用的模型和对应接口。
根据需求进入文本、图片、视频或音频的能力文档。

TIP

模型可用性由账号、分组和 API Key 权限共同决定。请始终以 GET /v1/models 的实际返回结果为准。

快速接入

在控制台创建并妥善保存 API Key。
用该 Key 查询可用模型，确认权限。
为不同能力调用对应接口，视频和图片接口不可混用。

Base URL 不要重复拼接

首选地址用于日常调用和大流量请求；备用地址需要由调用方配置故障切换。OpenAI SDK 的 base_url 应包含 /v1，自行拼接完整路径时不要重复添加 /v1。

查询可用模型

bash

curl -X GET "https://ai.silicogrove.com/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

最小文本测试

bash

curl -X POST "https://ai.silicogrove.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "你好，用一句话回复我"}]
  }'

Python OpenAI SDK

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai.silicogrove.com/v1",
)

response = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "你好，用一句话回复我"}],
)
print(response.choices[0].message.content)

模型与权限

可调用模型由账号、分组和 API Key 权限共同决定。始终以自己的 /v1/models 返回结果为准。

场景	常见模型示例	接口
文本	`gpt-5.4-mini`、Claude、Gemini 等	`/v1/chat/completions`
图片	`gpt-image-2`、Gemini 图片模型、`grok-imagine-image`	同步 `/v1/images/generations`；异步 `/v1/images/tasks`
视频	首推 `grok-video-1.5`（仅支持 6、8、10、12、15 秒）、`kling-video-v3`、`video-ds-2.0`、`as-sd2.0-fast`；`grok-imagine-video`、`grok-imagine-video-1.5`（当前下架）	`/v1/videos`
音频	以模型列表返回为准	`/v1/audio/*`

bash

curl -X GET "https://ai.silicogrove.com/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

文本聊天

Chat Completions

bash

curl -X POST "https://ai.silicogrove.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手"},
      {"role": "user", "content": "写一句产品介绍"}
    ],
    "stream": false
  }'

Responses API

bash

curl -X POST "https://ai.silicogrove.com/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.4-mini", "input": "用一句话介绍你自己"}'

图片生成与编辑

实际可用模型以 API Key 请求 GET /v1/models 的结果为准：

bash

curl "https://ai.silicogrove.com/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

模型	图片生成	图片编辑	OpenAI 图片协议	Gemini 原生协议
`gpt-image-2`	支持	支持	支持	不支持
`gpt-image-2-all`	取决于 `/v1/models` 是否可见	取决于上游	支持	不支持
`gemini-3-pro-image`	支持	支持	支持	支持
`gemini-3.1-flash-image`	支持	支持	支持	支持
`gemini-3-pro-image-preview`	支持	支持	支持	支持
`gemini-3.1-flash-image-preview`	支持	支持	支持	支持
`gemini-2.5-flash-image`	支持	支持	支持	支持
`grok-imagine-image`、`grok-imagine-image-pro`	取决于 `/v1/models` 是否可见	取决于上游	支持	不支持

推荐 Base URL 为 https://ai.silicogrove.com，备用地址为 https://api.silicogrove.com。所有请求使用 Authorization: Bearer YOUR_API_KEY 认证。

OpenAI 兼容生图

适用于 gpt-image-2 和 Gemini 图片模型。

bash

curl "https://ai.silicogrove.com/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张高级感产品海报，真实摄影风格，干净背景",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "response_format": "url"
  }'

Gemini 模型示例：

bash

curl "https://ai.silicogrove.com/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "一张 16:9 的雨夜霓虹城市图片",
    "size": "1792x1024",
    "quality": "2k",
    "n": 1,
    "response_format": "url"
  }'

OpenAI 兼容改图

使用 multipart/form-data。上传文件时不要手动填写 Content-Type，应让 curl 或 SDK 自动生成 multipart boundary。

bash

curl "https://ai.silicogrove.com/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=保持主体不变，把背景换成夜晚城市" \
  -F "image=@/path/to/input.png" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "n=1"

调用 Gemini 改图时将 model 改为 gemini-3.1-flash-image，并使用 quality=2k。

支持 PNG、JPG、JPEG、WebP。游乐场当前每次仅允许上传一张参考图，单文件最大 10 MB。

OpenAI 图片参数

以下是网关可接收的常用字段。具体模型可能只支持其中一部分；不支持的枚举可能被上游忽略或拒绝，请以模型能力和实际响应为准。

字段	类型	必填	常见值或限制	说明
`model`	string	是	以 `GET /v1/models` 为准	图片模型名称。
`prompt`	string	是	自然语言文本	生成或编辑要求。
`n`	integer	否	`1` 至 `10`；默认 `1`	生成数量。Gemini 图片模型应设置为 `1`，其他模型也可能有更小限制。
`size`	string	否	常见 `1024x1024`、`1536x1024`、`1024x1536`、`1792x1024`、`1024x1792`	尺寸或比例映射取决于模型。DALL-E 模型有更严格的尺寸枚举。
`quality`	string	否	常见 `auto`、`low`、`medium`、`high`、`standard`、`hd`、`1k`、`2k`、`4k`	质量或输出分辨率档位，区分大小写的行为取决于上游。
`response_format`	string	否	`url`、`b64_json`	同步接口的期望返回格式。异步任务最终只返回持久化后的 URL。
`background`	string	否	`auto`、`opaque`、`transparent`	背景模式，仅部分模型支持。
`output_format`	string	否	`png`、`jpeg`、`webp`	输出文件格式，仅部分模型支持。
`output_compression`	integer	否	通常 `0` 至 `100`	JPEG/WebP 压缩质量，仅部分模型支持。
`style`	string	否	常见 `vivid`、`natural`	风格选项，仅部分模型支持。
`moderation`	string	否	常见 `auto`、`low`	内容审核强度，仅部分模型支持。
`stream`	boolean	否	`true`、`false`	同步接口是否请求流式返回；异步任务必须为 `false` 或省略。
`image`、`image[]`	file 或模型支持的 JSON URL/值	改图时是	PNG、JPEG、WebP；multipart 单文件最大 `10 MB`	参考图。异步 multipart 文件会先保存再由 worker 发送。
`mask`	file 或模型支持的 JSON URL/值	否	通常为 PNG	编辑遮罩，仅部分模型支持。
`input_fidelity`	string	否	常见 `low`、`high`	参考图保真度，仅部分模型支持。

使用 curl -F 时不要手动设置 Content-Type。multipart 的 n、output_compression 等标量应作为文本表单字段发送。

OpenAI 兼容响应

R2 上传成功时返回 URL：

json

{"created":1786192453,"data":[{"url":"https://file.lunadownload.com/temporary/2026/08/12/uuid.png"}]}

R2 未配置或上传失败时返回 b64_json：

json

{"created":1786192453,"data":[{"b64_json":"iVBORw0KGgo..."}]}

字段	类型	说明
`created`	integer	上游返回的图片创建时间戳。
`data`	array	图片结果列表。
`data[].url`	string	R2 或上游图片 URL。URL 可能被定期清理。
`data[].b64_json`	string	Base64 图片。通常只在同步请求且 R2 未生效时出现。
`data[].revised_prompt`	string	上游改写后的提示词；仅部分模型返回。

临时图片链接

通过 file.lunadownload.com 返回的图片属于临时文件，系统会定期清理。请在生成完成后尽快下载并自行保存。

异步图片任务

当生图可能超过客户端或反向代理的同步超时时间时，使用异步接口。提交接口立即返回任务 ID，后台完成上游调用和 R2 持久化；同步接口保持原有行为不变。

操作	接口	请求格式
异步生图	`POST /v1/images/tasks`	JSON，不包含 `image`、`images` 或 `mask`
异步改图	`POST /v1/images/tasks`	multipart 上传文件，或包含图片字段的 JSON
查询任务	`GET /v1/images/tasks/{task_id}`	GET

异步接口必须启用本站 R2 存储，不支持 stream: true。异步改图上传的参考图单文件最大 10 MB。异步生成结果必须成功保存到 R2 才会标记为 completed；上游调用或持久化失败时任务标记为 failed，预扣额度会退还。

JSON 改图使用 image（单张）或 images（多张），每项为公网 HTTPS URL 或完整 data:image/...;base64,...。Gemini 图片模型会将这些引用转换为原生 inlineData；mask 不适用于 Gemini 改图。需要上传本地文件时，可先调用临时素材接口，该接口支持 API Key。

异步生图

bash

curl -X POST "https://ai.silicogrove.com/v1/images/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张高级感产品海报，真实摄影风格",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

异步改图

bash

curl -X POST "https://ai.silicogrove.com/v1/images/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=保持主体不变，把背景换成夜晚城市" \
  -F "image=@/path/to/input.png" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "n=1"

提交响应

提交成功返回 HTTP 202 Accepted：

json

{
  "id": "task_0123456789abcdef",
  "object": "image.task",
  "status": "queued",
  "progress": "0%",
  "created_at": 1786192453,
  "started_at": 0,
  "completed_at": 0
}

查询任务

bash

curl "https://ai.silicogrove.com/v1/images/tasks/task_0123456789abcdef" \
  -H "Authorization: Bearer YOUR_API_KEY"

任务只能由创建它的用户查询。建议每 2 至 5 秒轮询一次，不要高频并发查询。

字段	类型	出现条件	说明
`id`	string	始终	公开任务 ID，格式为 `task_...`。
`object`	string	始终	固定为 `image.task`。
`status`	string	始终	`queued`、`processing`、`completed` 或 `failed`。
`progress`	string	始终	百分比字符串，例如 `0%`、`10%`、`100%`。
`created_at`	integer	始终	任务提交 Unix 时间戳。
`started_at`	integer	始终	开始执行 Unix 时间戳；未开始时为 `0`。
`completed_at`	integer	始终	终态 Unix 时间戳；未完成时为 `0`。
`created`	integer	成功	图片结果中的创建时间戳。
`data`	array	成功	图片结果列表，主要读取 `data[].url`。
`error.message`	string	失败	任务失败原因。
`error.type`	string	失败	当前为 `image_task_failed`。

`status`	含义	是否终态
`queued`	已进入队列，等待后台执行	否
`processing`	正在调用上游或保存结果	否
`completed`	已完成，`data[].url` 可用	是
`failed`	执行失败，查看 `error`	是

成功响应：

json

{
  "id": "task_0123456789abcdef",
  "object": "image.task",
  "status": "completed",
  "progress": "100%",
  "created_at": 1786192453,
  "started_at": 1786192455,
  "completed_at": 1786192550,
  "created": 1786192548,
  "data": [{"url": "https://file.lunadownload.com/temporary/2026/08/12/uuid.png"}]
}

失败响应：

json

{
  "id": "task_0123456789abcdef",
  "object": "image.task",
  "status": "failed",
  "progress": "100%",
  "created_at": 1786192453,
  "started_at": 1786192455,
  "completed_at": 1786192550,
  "error": {"message": "upstream request failed", "type": "image_task_failed"}
}

异步 HTTP 状态码

状态码	场景
`202`	任务创建成功。
`400`	参数、multipart 文件、`n` 或 `stream` 无效。
`403`	API Key、额度、分组或模型权限不足。
`404`	任务不存在、类型不匹配，或不属于当前用户。
`429`	请求频率或模型并发受限。
`503`	异步任务所需的 R2 存储未配置或不可用。

提交或查询请求在进入任务状态前失败时，使用统一错误结构：

json

{
  "error": {
    "message": "R2 storage is required for asynchronous image tasks",
    "type": "storage_unavailable",
    "code": "storage_unavailable"
  }
}

当前没有 /v1/images/tasks/{task_id}/content 接口，请直接下载完成响应中的 data[].url。

Gemini 原生生图

仅适用于 Gemini 图片模型，gpt-image-2 不支持此协议。

bash

curl "https://ai.silicogrove.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role":"user","parts":[{"text":"生成一张 16:9 的雨夜霓虹城市图片"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio":"16:9","imageSize":"2K"}
    }
  }'

Gemini 原生改图

Gemini 没有单独的原生 edits endpoint。生图和改图都调用 generateContent；改图时需在 parts 中增加参考图片的 inlineData。

bash

IMAGE_B64=$(base64 < input.png | tr -d '\n')

curl "https://ai.silicogrove.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"contents\":[{\"role\":\"user\",\"parts\":[
      {\"text\":\"保持主体不变，把背景换成夜晚城市\"},
      {\"inlineData\":{\"mimeType\":\"image/png\",\"data\":\"${IMAGE_B64}\"}}
    ]}],
    \"generationConfig\":{\"responseModalities\":[\"TEXT\",\"IMAGE\"],\"imageConfig\":{\"aspectRatio\":\"1:1\",\"imageSize\":\"2K\"}}
  }"

R2 上传成功后，生成图片以 fileData.fileUri 返回；R2 上传失败时保留 Gemini 原始 inlineData base64。

Gemini 参数映射

使用 OpenAI 图片协议调用 Gemini 模型时，参数会按以下规则转换：

OpenAI 参数	Gemini 原生字段
`prompt`	`contents[].parts[].text`
`image` 文件	`contents[].parts[].inlineData`
`size: 1024x1024`	`aspectRatio: 1:1`
`size: 1792x1024`	`aspectRatio: 16:9`
`size: 1024x1792`	`aspectRatio: 9:16`
`size: 1536x1024`	`aspectRatio: 3:2`
`size: 1024x1536`	`aspectRatio: 2:3`
`quality: auto`、`fast`、`1k`	`imageSize: 1K`
`quality: high`、`hd`、`2k`	`imageSize: 2K`
`quality: 4k`	`imageSize: 4K`

Gemini 图片模型当前每次只能生成一张图片，应设置 n: 1。

视频生成

视频生成是异步任务。通过 POST /v1/videos 创建任务，保存返回的任务 ID，再轮询 GET /v1/videos/{task_id} 直到任务结束。视频模型不能发送到 /v1/chat/completions。

可调用模型取决于 API Key 和用户分组。向最终用户展示模型前，请先调用 GET /v1/models。

首推模型：Grok Video 1.5

模型	时长	分辨率
`grok-video-1.5`	默认 15 秒；可指定 `6`、`8`、`10`、`12`、`15` 秒	可选；建议 `720p`

grok-video-1.5 同时支持文生视频、单参考图和多参考图（最多 7 张）。以下三个实例使用相同的接口，仅需根据是否有参考图调整 image_urls。

WARNING

不传 seconds 时默认生成 15 秒。显式传入时，seconds 只能是字符串 "6"、"8"、"10"、"12" 或 "15"。传入 "4" 或其他值会返回：seconds must be one of: 6, 8, 10, 12, 15。

其他支持的可灵 V3 模型

模型	时长	分辨率	计费方式
`kling-video-v3`	3-15 秒	`720p`、`1080p`、`4k`	按秒和所选分辨率计费
`kling-video-v3-omni`	3-15 秒	`720p`、`1080p`、`4k`	按秒和所选分辨率计费
`kling-video-v3-turbo`	3-15 秒	`720p`、`1080p`	按秒和所选分辨率计费

创建可灵任务时将 resolution 作为顶层字段传递。不要使用图像生成的 quality 字段表示视频分辨率。实际价格以提交任务时的计算结果为准，不要依赖文档中的固定金额。

Grok Video 1.5 调用实例

所有实例均使用 POST /v1/videos、Authorization: Bearer YOUR_API_KEY 和 Content-Type: application/json。

1. 文生视频

bash

curl -X POST "https://ai.silicogrove.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video-1.5",
    "prompt": "日出照亮未来海滨城市，航拍镜头缓慢前移，电影感光影",
    "seconds": "15",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

2. 单参考图视频

json

{
  "model": "grok-video-1.5",
  "prompt": "让产品平稳旋转，柔和棚拍光线，干净的商业广告镜头",
  "seconds": "10",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "image_urls": ["https://example.com/product.png"]
}

3. 多参考图视频

json

{
  "model": "grok-video-1.5",
  "prompt": "使用这些参考图制作连贯的产品展示视频，电影感运镜与高级商业灯光",
  "seconds": "15",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "image_urls": [
    "https://example.com/product-front.png",
    "https://example.com/product-detail.png"
  ]
}

响应会包含公开的 id 或 task_id。请保存该值；不要使用其他上游响应中的内部任务 ID。

json

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "status": "queued"
}

该示例使用首推模型 grok-video-1.5 创建 15 秒的文生视频。创建成功后会立即返回异步任务；保存 task_id，再用查询任务接口获取进度和结果。

json

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video.generation",
  "model": "grok-video-1.5",
  "status": "queued",
  "progress": 0,
  "created_at": 1786869597,
  "result": {}
}

参考素材

参考图可以使用公网 HTTPS URL，或完整的 data: URL，例如 data:image/png;base64,...。不要传本地文件路径或裸 base64。可先通过临时素材接口上传本地文件。

推荐使用 image_urls。为兼容既有接入，images 也可用，但二者不能同时传递。reference_images 以及 input_reference: {"image_url":"..."} 也可用于兼容接入；同一请求不能同时传 reference_images 和 input_reference。

请求字段

字段	是否必填	说明
`model`	是	API Key 可调用的视频模型。
`prompt`	是	建议描述主体、动作、镜头、视觉风格和构图。
`seconds`	否	请求时长，字符串；不传时 `grok-video-1.5` 默认 15 秒。显式传入仅支持 `"6"`、`"8"`、`"10"`、`"12"`、`"15"`。
`aspect_ratio`	否	`16:9`、`9:16` 或 `1:1`。
`resolution`	Kling V3 必填；Grok 可选	Grok 建议传 `720p`；Kling 支持 `480p`、`720p`、`1080p` 或 `4k`，取决于所选模型。作为顶层字段传递，不要用 `quality` 代替。
`image_urls`	否	推荐字段，最多 7 个参考图 URL 或完整 data URL。
`images`	否	`image_urls` 的兼容别名；不能同时传。
`image`	否	仅用于 `grok-imagine-video-1.5` 的首帧模式。传单个图片 URL 或完整 data URL；不能与 `reference_images` 同时传。
`reference_images`	否	参考图兼容字段；不能与 `input_reference` 同时传。
`input_reference`	否	单参考图兼容形式：`{ "image_url": "https://..." }`。

旧版 video-ds-* 模型支持 images、videos、audios，数量上限分别为 4 张图片、3 个视频和 1 个音频。

查询任务

bash

curl -X GET "https://ai.silicogrove.com/v1/videos/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

queued、in_progress 表示任务仍在处理中；completed 表示视频已可用；failed 表示生成失败。建议每 5 秒轮询一次；客户端超时时保留任务 ID，稍后继续查询。

下载完成的视频

bash

curl -L "https://ai.silicogrove.com/v1/videos/TASK_ID/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.mp4

服务内部可能返回带签名的临时结果链接，应及时下载。请使用上述内容接口，不要自行拼接上游域名、任务 ID 或签名参数。

安全与稳定建议

密钥与调用侧

只在服务端的环境变量或密钥管理服务中保存 API Key。浏览器、移动端和公开前端代码不应持有长期 Key。
按应用或用途拆分 API Key。发生异常时可单独吊销受影响的 Key，不影响其他业务。
创建任务后，将本地业务单号与返回的 task_id 一并保存，用于查询、对账和重试控制。

参考素材与下载侧

参考素材 URL 必须可由视频服务安全访问。不要传入内网 IP、管理地址、云凭据链接或本地文件路径。
任务完成后通过受鉴权的 /content 接口下载视频，不要将临时结果地址长期公开。
仅在任务已明确返回 failed 后创建新任务重试。对于 queued 或 in_progress 状态，应继续查询同一个 task_id，避免重复生成和重复计费。

Grok Imagine 模型（当前下架）

WARNING

grok-imagine-video 与 grok-imagine-video-1.5 当前已下架，不能用于生产调用。以下内容仅保留为历史参数参考；请使用上文已接通的可灵模型。

模型	生成方式	时长	分辨率
`grok-imagine-video`	文生视频	取决于模型	取决于模型
`grok-imagine-video-1.5`	文生视频、首帧图生视频、参考图生视频	`4`、`6`、`8`、`10`、`12`、`15` 秒	文生和首帧支持 `480p`、`720p`、`1080p`；参考图最高 `720p`

grok-imagine-video-1.5 有两种互斥的图片模式：首帧模式传 1 个 image URL；参考图模式传 1-7 个 reference_images URL，并在提示词中使用 <IMAGE_1>、<IMAGE_2> 等占位符。不要将 image、images、image_urls 或 input_reference 与 reference_images 同时传递。参考图模式仅支持最高 720p。

历史请求示例：

json

{
  "model": "grok-imagine-video-1.5",
  "prompt": "让 <IMAGE_1> 中的人物在城市街道中行走，电影感商业广告镜头",
  "reference_images": ["https://example.com/person.jpg"],
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}

上传参考素材

本地图片、视频和音频可先上传到临时素材接口。该接口接受 API Key（也接受游乐场登录态），因此 API 客户端可先上传本地文件，再将返回的 data.url 放入后续请求。

上传成功后的 data.url 可直接放入视频请求中的 images、videos 或 audios 数组；也可作为 Gemini OpenAI 兼容改图请求的 JSON 图片引用。

临时文件会定期清理

上传素材和生成结果均为临时文件，系统会定期清理，链接可能失效。请在使用或任务完成后尽快下载并自行保存；请勿将返回链接作为长期存储地址。

上传文件

bash

# 上传图片
curl -X POST "https://ai.silicogrove.com/pg/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "kind=image" \
  -F "file=@/path/to/ref.jpg"

# 上传视频
curl -X POST "https://ai.silicogrove.com/pg/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "kind=video" \
  -F "file=@/path/to/ref.mp4"

# 上传音频
curl -X POST "https://ai.silicogrove.com/pg/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "kind=audio" \
  -F "file=@/path/to/ref.mp3"

返回示例

json

{
  "success": true,
  "data": {
    "kind": "image",
    "url": "https://file.lunadownload.com/temporary/2026/08/11/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.jpg",
    "filename": "ref.jpg",
    "content_type": "image/jpeg",
    "size": 123456
  }
}

`kind`	文件类型	单文件大小
`image`	jpg、png、webp	最多 10 MiB
`video`	mp4、mov、webm	最多 100 MiB
`audio`	mp3、m4a、wav、aac、ogg、webm	最多 20 MiB

音频

语音合成

bash

curl -X POST "https://ai.silicogrove.com/v1/audio/speech" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_TTS_MODEL",
    "input": "欢迎使用 Silico Grove API。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

音频转写与翻译

bash

curl -X POST "https://ai.silicogrove.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=YOUR_STT_MODEL" \
  -F "file=@/path/to/audio.mp3" \
  -F "response_format=json"

curl -X POST "https://ai.silicogrove.com/v1/audio/translations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=YOUR_STT_MODEL" \
  -F "file=@/path/to/audio.mp3" \
  -F "response_format=json"

转写和翻译必须使用 multipart，文件字段名为 file。

常见错误

现象	常见原因	处理方式
模型不可用	模型和分组不匹配，或 Key 没有权限。	用同一个 Key 请求 `/v1/models` 确认模型名。
`model is required`	字段名被二次中转改写。	保留 `model`，不要改成 `model_name`。
视频失败或走聊天模型	视频请求发到了聊天接口。	视频必须调用 `POST /v1/videos`。
参考素材未生效	传了本地路径，或字段不是数组。	传公网 URL，分别填入 `images`、`videos`、`audios`。
`seconds` 类型错误	把时长传成数字。	使用字符串，例如 `"seconds": "15"`。
上传失败	手写了错误的 Content-Type，或字段名错误。	使用 `-F`；文件字段名为 `file`。

排查问题时，请提供请求时间、模型名、接口路径、分组、request ID 和错误内容。请勿公开完整 API Key、Authorization 请求头或敏感提示词。

二次中转注意事项

首选上游地址填写 https://ai.silicogrove.com 或 https://ai.silicogrove.com/v1，取决于中转系统是否自动补全 /v1。
备用地址为 https://api.silicogrove.com 或 https://api.silicogrove.com/v1；需要由中转系统配置故障切换，不会自动生效。
使用 Silico Grove 的 API Key 同步 /v1/models，不要手填不存在的模型。
视频模型 endpoint 必须为 /v1/videos，不要放入聊天模型池。
转发视频请求时保留 JSON 原字段，尤其是 images、videos、audios 数组。
图片编辑与音频转写是 multipart 请求，转发时不要丢失文件字段。
异步图片统一提交到 POST /v1/images/tasks，并轮询 GET /v1/images/tasks/{task_id}；不要将异步任务包装成同步图片响应。

给普通用户和二次中转用户的接入手册 ​

服务地址 ​

阅读顺序 ​

快速接入 ​

查询可用模型 ​

最小文本测试 ​

Python OpenAI SDK ​

模型与权限 ​

文本聊天 ​

Chat Completions ​

Responses API ​

图片生成与编辑 ​

OpenAI 兼容生图 ​

OpenAI 兼容改图 ​

OpenAI 图片参数 ​

OpenAI 兼容响应 ​

异步图片任务 ​

异步生图 ​

异步改图 ​

提交响应 ​

查询任务 ​

异步 HTTP 状态码 ​

Gemini 原生生图 ​

Gemini 原生改图 ​

Gemini 参数映射 ​

推荐方案 ​

视频生成 ​

首推模型：Grok Video 1.5 ​

其他支持的可灵 V3 模型 ​

Grok Video 1.5 调用实例 ​

1. 文生视频 ​

2. 单参考图视频 ​

3. 多参考图视频 ​

参考素材 ​

请求字段 ​

查询任务 ​

下载完成的视频 ​

安全与稳定建议 ​

密钥与调用侧 ​

参考素材与下载侧 ​

Grok Imagine 模型（当前下架） ​

上传参考素材 ​

上传文件 ​

返回示例 ​

音频 ​

语音合成 ​

音频转写与翻译 ​

常见错误 ​

二次中转注意事项 ​

给普通用户和二次中转用户的接入手册

服务地址

阅读顺序

快速接入

查询可用模型

最小文本测试

Python OpenAI SDK

模型与权限

文本聊天

Chat Completions

Responses API

图片生成与编辑

OpenAI 兼容生图

OpenAI 兼容改图

OpenAI 图片参数

OpenAI 兼容响应

异步图片任务

异步生图

异步改图

提交响应

查询任务

异步 HTTP 状态码

Gemini 原生生图

Gemini 原生改图

Gemini 参数映射

推荐方案

视频生成

首推模型：Grok Video 1.5

其他支持的可灵 V3 模型

Grok Video 1.5 调用实例

1. 文生视频

2. 单参考图视频

3. 多参考图视频

参考素材

请求字段

查询任务

下载完成的视频

安全与稳定建议

密钥与调用侧

参考素材与下载侧

Grok Imagine 模型（当前下架）

上传参考素材

上传文件

返回示例

音频

语音合成

音频转写与翻译

常见错误

二次中转注意事项