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

按本手册可接入文本、图片、视频和音频能力。不同能力应使用对应 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 图片模型	`/v1/images/generations`
视频	`video-ds-2.0`、`as-sd2.0-fast`	`/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": "用一句话介绍你自己"}'

图片生成与编辑

图片生成

bash

curl -X POST "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": "auto",
    "n": 1,
    "response_format": "url"
  }'

字段	说明
`model`	必填，必须是 Key 可见的图片模型。
`prompt`	必填，图片描述。
`size`	可选，例如 `1024x1024` 或模型支持的比例。
`quality`	可选，常见值为 `auto`、`low`、`high`、`2K`、`4K`。

图片编辑

上传本地图片时，使用 multipart 请求：

bash

curl -X POST "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"

WARNING

使用 -F 时不要手写 Content-Type: application/json。图片字段名为 image，遮罩字段名为 mask。

视频生成

视频模型必须使用 POST /v1/videos，不能作为聊天模型发送到 /v1/chat/completions。提交后会返回任务 ID，需要轮询查询。

最小文生视频示例

bash

curl -X POST "https://ai.silicogrove.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "video-ds-2.0-fast",
    "prompt": "A cinematic 9:16 short video, neon city rooftop at night, realistic lighting, no watermark.",
    "seconds": "15",
    "aspect_ratio": "9:16"
  }'

多媒体参考示例

TIP

参考素材必须是公网可访问 URL。可使用自己的对象存储 URL，或先上传到临时素材接口。不要在 JSON 中填写本地文件路径。

bash

curl -X POST "https://ai.silicogrove.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "video-ds-2.0",
    "prompt": "参考图片的人物形象，参考视频的动作节奏，生成一段自然流畅的 9:16 视频",
    "seconds": "15",
    "aspect_ratio": "9:16",
    "images": ["https://example.com/ref-1.jpg"],
    "videos": ["https://example.com/motion.mp4"],
    "audios": ["https://example.com/music.mp3"]
  }'

字段	限制	说明
`model`	必填	必须是 Key 可见的视频模型。
`prompt`	必填	建议明确主体、动作、镜头、风格与比例。
`seconds`	建议填写	字符串，例如 `"5"`、`"10"`、`"15"`。
`aspect_ratio`	建议填写	`16:9`、`9:16` 或 `1:1`。
`images`	最多 4 张	jpg、png、webp 的 URL 数组。
`videos`	最多 3 个	mp4、mov、webm 的 URL 数组。
`audios`	最多 1 个	mp3、m4a、wav、aac、ogg 的 URL 数组。

上述参考素材数量限制适用于 video-ds-2.0、video-ds-2.0-fast 和 as-sd2.0-fast；其他视频模型的支持能力可能不同。

查询任务与下载视频

bash

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

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

上传参考素材

本地图片、视频和音频可先上传到临时素材接口。上传成功后的 data.url 可直接放入视频请求中的 images、videos 或 audios 数组。

临时素材的保留时间

临时素材会在 24 小时后自动删除。需要长期保留时，请使用自己的对象存储或 CDN URL。

上传文件

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 请求，转发时不要丢失文件字段。

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

服务地址 ​

阅读顺序 ​

快速接入 ​

查询可用模型 ​

最小文本测试 ​

Python OpenAI SDK ​

模型与权限 ​

文本聊天 ​

Chat Completions ​

Responses API ​

图片生成与编辑 ​

图片生成 ​

图片编辑 ​

视频生成 ​

最小文生视频示例 ​

多媒体参考示例 ​

查询任务与下载视频 ​

上传参考素材 ​

上传文件 ​

返回示例 ​

音频 ​

语音合成 ​

音频转写与翻译 ​

常见错误 ​

二次中转注意事项 ​

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

服务地址

阅读顺序

快速接入

查询可用模型

最小文本测试

Python OpenAI SDK

模型与权限

文本聊天

Chat Completions

Responses API

图片生成与编辑

图片生成

图片编辑

视频生成

最小文生视频示例

多媒体参考示例

查询任务与下载视频

上传参考素材

上传文件

返回示例

音频

语音合成

音频转写与翻译

常见错误

二次中转注意事项