SilicoGrove 生图接口接入示例：cURL、Python、Java、Go 完整 Demo

下面直接以 SilicoGrove 的图片生成接口为例，给出一套可以直接复制使用的接入 Demo。

SilicoGrove 当前推荐的 API Base URL 是：

text 复制代码

https://ai.silicogrove.com/v1

备用地址：

text 复制代码

https://api.silicogrove.com/v1

所有请求统一使用：

http 复制代码

Authorization: Bearer YOUR_API_KEY

进行认证。

本文主要演示：

text 复制代码

POST /v1/images/generations

也就是 OpenAI 兼容的同步生图接口。

完整地址：

text 复制代码

https://ai.silicogrove.com/v1/images/generations

当前文档列出的图片模型包括：

text 复制代码

gpt-image-2

gpt-image-2-all

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

不过具体能调用哪些模型，要以自己的 API Key 请求：

text 复制代码

GET /v1/models

返回的结果为准。

一、先看最简单的请求

我们以：

text 复制代码

gpt-image-2

为例。

请求内容：

json 复制代码

{
  "model": "gpt-image-2",
  "prompt": "一只橘猫坐在未来科技城市的楼顶，电影级摄影，夕阳，超高细节",
  "size": "1024x1024",
  "quality": "high",
  "n": 1,
  "response_format": "url"
}

这个请求的意思就是：

使用 gpt-image-2 生成 1 张 1024×1024、高质量的图片，并希望接口最终返回图片 URL。

SilicoGrove 的 OpenAI 兼容图片接口支持诸如 model、prompt、n、size、quality、response_format、background、output_format、output_compression 等字段，但不同模型支持的具体参数存在差异。

二、cURL Demo

这是最推荐用来测试接口是否正常的方法。

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": "high",
    "n": 1,
    "response_format": "url"
  }'

把：

text 复制代码

YOUR_API_KEY

替换成自己的 API Key 即可。

例如：

bash 复制代码

curl -X POST "https://ai.silicogrove.com/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一辆黑色超级跑车停在赛博朋克东京街头，雨夜，霓虹灯，电影摄影",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "response_format": "url"
  }'

三、cURL 返回结果

如果图片生成成功，并且 SilicoGrove 的图片存储正常，返回大致如下：

json 复制代码

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

SilicoGrove 会在图片成功保存到对象存储后返回 URL。

其中：

json 复制代码

{
  "created": 1786192453
}

表示图片创建时间。

这是：

text 复制代码

Unix 时间戳

而：

json 复制代码

{
  "data": []
}

表示生成结果数组。

如果一次生成一张：

json 复制代码

"n": 1

通常就是：

json 复制代码

data[0]

如果最终返回 URL：

json 复制代码

{
  "url": "https://file.lunadownload.com/temporary/xxx.png"
}

那么直接访问这个 URL 就可以获得生成后的图片。

需要注意，SilicoGrove 文档明确说明，通过 file.lunadownload.com 返回的图片属于临时文件，会定期清理，因此生成成功后建议尽快下载或者转存到自己的对象存储。

四、另外一种返回：Base64

如果 R2 存储没有配置成功，或者上传失败，同步接口可能返回：

json 复制代码

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

其中：

text 复制代码

b64_json

就是图片的 Base64 数据。

也就是说调用方最好同时兼容：

text 复制代码

data[0].url

以及：

text 复制代码

data[0].b64_json

两种情况。

推荐逻辑：

text 复制代码

请求成功
   │
   ▼
检查 data[0].url
   │
   ├── 有 → 直接使用图片 URL
   │
   └── 没有
         │
         ▼
   检查 data[0].b64_json
         │
         └── Base64 解码保存图片

五、Python Demo

Python 最简单可以直接使用：

text 复制代码

requests

安装：

bash 复制代码

pip install requests

完整代码：

python 复制代码

import requests

API_KEY = "YOUR_API_KEY"

url = "https://ai.silicogrove.com/v1/images/generations"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "prompt": "一只橘猫坐在未来科技城市的楼顶，电影级摄影，夕阳，超高细节",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "response_format": "url"
}

response = requests.post(
    url,
    headers=headers,
    json=payload,
    timeout=600
)

print("HTTP Status:", response.status_code)
print(response.text)

这里建议：

python 复制代码

timeout=600

不要设置太短。

因为图片生成相比普通文本请求通常明显更慢。

六、Python 获取图片 URL

实际开发中通常不会直接：

python 复制代码

print(response.text)

而是解析 JSON：

python 复制代码

import requests

API_KEY = "YOUR_API_KEY"

url = "https://ai.silicogrove.com/v1/images/generations"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "prompt": "一只橘猫在草原上奔跑，电影纪录片风格，真实摄影",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "response_format": "url"
}

response = requests.post(
    url,
    headers=headers,
    json=payload,
    timeout=600
)

response.raise_for_status()

result = response.json()

image_url = result["data"][0].get("url")

if image_url:
    print("图片地址：")
    print(image_url)
else:
    print("没有返回图片 URL")

七、Python 自动下载图片

还可以直接把图片下载到本地。

完整 Demo：

python 复制代码

import requests

API_KEY = "YOUR_API_KEY"

url = "https://ai.silicogrove.com/v1/images/generations"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "prompt": "一只橘猫坐在宇宙飞船驾驶舱里，电影级画面，真实摄影",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "response_format": "url"
}

response = requests.post(
    url,
    headers=headers,
    json=payload,
    timeout=600
)

response.raise_for_status()

result = response.json()

item = result["data"][0]

if "url" in item:

    image_url = item["url"]

    print("生成成功：", image_url)

    image_response = requests.get(
        image_url,
        timeout=120
    )

    image_response.raise_for_status()

    with open("output.png", "wb") as f:
        f.write(image_response.content)

    print("图片已保存：output.png")

else:
    print("接口没有返回 URL")

八、Python 同时兼容 URL 和 Base64

实际项目中，更推荐写成这样：

python 复制代码

import requests
import base64

API_KEY = "YOUR_API_KEY"

url = "https://ai.silicogrove.com/v1/images/generations"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "prompt": "未来城市中的中国龙，赛博朋克风格，电影级画面",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "response_format": "url"
}

response = requests.post(
    url,
    headers=headers,
    json=payload,
    timeout=600
)

response.raise_for_status()

result = response.json()

item = result["data"][0]

if item.get("url"):

    image_url = item["url"]

    print("图片 URL:", image_url)

elif item.get("b64_json"):

    image_data = base64.b64decode(
        item["b64_json"]
    )

    with open("output.png", "wb") as f:
        f.write(image_data)

    print("Base64 图片已保存到 output.png")

else:

    print("没有找到图片数据")

这个版本更加适合生产环境。

九、Python 使用 OpenAI SDK

因为 SilicoGrove 提供的是 OpenAI 兼容协议，也可以尝试直接使用 OpenAI SDK。

安装：

bash 复制代码

pip install openai

然后：

python 复制代码

from openai import OpenAI

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

result = client.images.generate(
    model="gpt-image-2",
    prompt="一只橘猫坐在未来科技城市的楼顶，电影摄影风格",
    size="1024x1024",
    quality="high",
    n=1
)

print(result)

注意 Base URL 一定是：

text 复制代码

https://ai.silicogrove.com/v1

不要写成：

text 复制代码

https://ai.silicogrove.com/v1/v1

SilicoGrove 文档也特别提醒，使用 OpenAI SDK 时 base_url 应当包含 /v1，自行拼完整接口路径时不要重复 /v1。

十、Java Demo

Java 可以直接使用 JDK 11+ 自带的：

text 复制代码

HttpClient

这样不需要额外引入 HTTP 库。

完整示例：

java 复制代码

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ImageDemo {

    private static final String API_KEY = "YOUR_API_KEY";

    public static void main(String[] args) throws Exception {

        String url =
                "https://ai.silicogrove.com/v1/images/generations";

        String body = """
                {
                  "model": "gpt-image-2",
                  "prompt": "一只橘猫坐在未来科技城市的楼顶，电影级摄影，夕阳",
                  "size": "1024x1024",
                  "quality": "high",
                  "n": 1,
                  "response_format": "url"
                }
                """;

        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(30))
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .timeout(Duration.ofMinutes(10))
                .header(
                        "Authorization",
                        "Bearer " + API_KEY
                )
                .header(
                        "Content-Type",
                        "application/json"
                )
                .POST(
                        HttpRequest.BodyPublishers.ofString(body)
                )
                .build();

        HttpResponse<String> response =
                client.send(
                        request,
                        HttpResponse.BodyHandlers.ofString()
                );

        System.out.println(
                "HTTP Status: " + response.statusCode()
        );

        System.out.println(
                response.body()
        );
    }
}

十一、Java + Jackson 解析返回

生产环境肯定不会自己处理字符串。

可以使用：

text 复制代码

Jackson

Maven：

xml 复制代码

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.18.2</version>
</dependency>

代码：

java 复制代码

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ImageDemo {

    private static final String API_KEY = "YOUR_API_KEY";

    public static void main(String[] args) throws Exception {

        String url =
                "https://ai.silicogrove.com/v1/images/generations";

        ObjectMapper mapper = new ObjectMapper();

        String body = """
                {
                  "model": "gpt-image-2",
                  "prompt": "赛博朋克风格未来城市，电影级摄影",
                  "size": "1024x1024",
                  "quality": "high",
                  "n": 1,
                  "response_format": "url"
                }
                """;

        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(30))
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .timeout(Duration.ofMinutes(10))
                .header(
                        "Authorization",
                        "Bearer " + API_KEY
                )
                .header(
                        "Content-Type",
                        "application/json"
                )
                .POST(
                        HttpRequest.BodyPublishers.ofString(body)
                )
                .build();

        HttpResponse<String> response =
                client.send(
                        request,
                        HttpResponse.BodyHandlers.ofString()
                );

        if (response.statusCode() != 200) {

            System.out.println(
                    "请求失败："
                            + response.body()
            );

            return;
        }

        JsonNode root =
                mapper.readTree(
                        response.body()
                );

        JsonNode first =
                root.path("data").get(0);

        if (first.has("url")) {

            String imageUrl =
                    first.path("url").asText();

            System.out.println(
                    "图片 URL："
                            + imageUrl
            );

        } else if (first.has("b64_json")) {

            System.out.println(
                    "接口返回 Base64 图片"
            );
        }
    }
}

十二、Go Demo

如果你使用 Go，直接使用标准库：

text 复制代码

net/http

即可。

完整代码：

go 复制代码

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"time"
)

const apiKey = "YOUR_API_KEY"

type ImageRequest struct {
	Model          string `json:"model"`
	Prompt         string `json:"prompt"`
	Size           string `json:"size"`
	Quality        string `json:"quality"`
	N              int    `json:"n"`
	ResponseFormat string `json:"response_format"`
}

func main() {

	url := "https://ai.silicogrove.com/v1/images/generations"

	payload := ImageRequest{
		Model:          "gpt-image-2",
		Prompt:         "一只橘猫坐在未来科技城市的楼顶，电影级摄影，夕阳",
		Size:           "1024x1024",
		Quality:        "high",
		N:              1,
		ResponseFormat: "url",
	}

	body, err := json.Marshal(payload)

	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest(
		http.MethodPost,
		url,
		bytes.NewBuffer(body),
	)

	if err != nil {
		panic(err)
	}

	req.Header.Set(
		"Authorization",
		"Bearer "+apiKey,
	)

	req.Header.Set(
		"Content-Type",
		"application/json",
	)

	client := &http.Client{
		Timeout: 10 * time.Minute,
	}

	resp, err := client.Do(req)

	if err != nil {
		panic(err)
	}

	defer resp.Body.Close()

	data, err := io.ReadAll(resp.Body)

	if err != nil {
		panic(err)
	}

	fmt.Println(
		"HTTP Status:",
		resp.StatusCode,
	)

	fmt.Println(
		string(data),
	)
}

十三、Go 解析图片 URL

定义返回结构：

go 复制代码

type ImageResponse struct {

	Created int64 `json:"created"`

	Data []struct {

		URL string `json:"url"`

		Base64 string `json:"b64_json"`

		RevisedPrompt string `json:"revised_prompt"`

	} `json:"data"`
}

完整处理：

go 复制代码

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"time"
)

const apiKey = "YOUR_API_KEY"

type ImageRequest struct {
	Model          string `json:"model"`
	Prompt         string `json:"prompt"`
	Size           string `json:"size"`
	Quality        string `json:"quality"`
	N              int    `json:"n"`
	ResponseFormat string `json:"response_format"`
}

type ImageResponse struct {
	Created int64 `json:"created"`

	Data []struct {
		URL           string `json:"url"`
		Base64        string `json:"b64_json"`
		RevisedPrompt string `json:"revised_prompt"`
	} `json:"data"`
}

func main() {

	url :=
		"https://ai.silicogrove.com/v1/images/generations"

	payload := ImageRequest{
		Model: "gpt-image-2",

		Prompt:
			"一只橘猫坐在未来科技城市楼顶，电影级摄影",

		Size:
			"1024x1024",

		Quality:
			"high",

		N:
			1,

		ResponseFormat:
			"url",
	}

	requestBody, _ :=
		json.Marshal(payload)

	req, err :=
		http.NewRequest(
			http.MethodPost,
			url,
			bytes.NewReader(requestBody),
		)

	if err != nil {
		panic(err)
	}

	req.Header.Set(
		"Authorization",
		"Bearer "+apiKey,
	)

	req.Header.Set(
		"Content-Type",
		"application/json",
	)

	client := &http.Client{
		Timeout:
			10 * time.Minute,
	}

	resp, err :=
		client.Do(req)

	if err != nil {
		panic(err)
	}

	defer resp.Body.Close()

	body, _ :=
		io.ReadAll(resp.Body)

	if resp.StatusCode != http.StatusOK {

		fmt.Println(
			"请求失败:",
			string(body),
		)

		return
	}

	var result ImageResponse

	err = json.Unmarshal(
		body,
		&result,
	)

	if err != nil {
		panic(err)
	}

	if len(result.Data) == 0 {

		fmt.Println(
			"没有返回图片",
		)

		return
	}

	image := result.Data[0]

	if image.URL != "" {

		fmt.Println(
			"图片 URL:",
			image.URL,
		)

		return
	}

	if image.Base64 != "" {

		fmt.Println(
			"接口返回 Base64 图片",
		)
	}
}

十四、主要请求参数解释

SilicoGrove 当前文档中，OpenAI 图片协议常用字段如下。

参数	类型	必填	说明
`model`	string	是	使用的图片模型
`prompt`	string	是	图片生成提示词
`n`	integer	否	生成图片数量，默认 `1`
`size`	string	否	图片尺寸
`quality`	string	否	图片质量
`response_format`	string	否	`url` 或 `b64_json`
`background`	string	否	背景模式
`output_format`	string	否	PNG、JPEG、WebP
`output_compression`	integer	否	JPEG/WebP 压缩质量
`style`	string	否	风格，例如 vivid、natural
`moderation`	string	否	内容审核等级
`stream`	boolean	否	是否流式

十五、model

例如：

json 复制代码

{
  "model": "gpt-image-2"
}

表示调用：

text 复制代码

gpt-image-2

也可以根据 /v1/models 中实际可用的模型修改为 Gemini 图片模型等。文档当前列出的 Gemini 图片模型同样可以通过 OpenAI 兼容的 /v1/images/generations 接口调用。

十六、prompt

这是最核心的字段。

例如：

json 复制代码

{
  "prompt": "一只橘猫坐在草原上，夕阳，真实摄影，电影纪录片画面"
}

简单理解：

text 复制代码

你想让 AI 画什么

就写什么。

一般建议 Prompt 包含：

text 复制代码

主体
+
环境
+
动作
+
镜头
+
光线
+
风格
+
细节

例如：

text 复制代码

一只成年橘猫站在非洲草原上，
正警惕地观察远处的兔子，
低机位跟拍，
夕阳逆光，
长焦摄影，
BBC 动物纪录片风格，
真实毛发，
电影级画面。

十七、size

例如：

json 复制代码

{
  "size": "1024x1024"
}

文档当前列出的常见尺寸包括：

text 复制代码

但不同模型支持的具体尺寸可能不同。

比如：

正方形

text 复制代码

1024x1024

适合：

text 复制代码

头像
商品图
Logo
小红书
社交媒体

横图

text 复制代码

1536x1024

或者：

text 复制代码

1792x1024

适合：

text 复制代码

文章封面
Banner
电脑壁纸
视频素材

竖图

text 复制代码

1024x1536

或者：

text 复制代码

1024x1792

适合：

text 复制代码

手机壁纸
短视频封面
海报
人物写真

十八、quality

例如：

json 复制代码

{
  "quality": "high"
}

SilicoGrove 网关目前可以接收的常见质量值包括：

text 复制代码

auto

low

medium

high

standard

hd

1k

2k

4k

具体支持情况取决于所选模型和上游。

例如 GPT 图片模型：

json 复制代码

{
  "model": "gpt-image-2",
  "quality": "high"
}

而 Gemini 图片模型可能使用：

json 复制代码

{
  "model": "gemini-3.1-flash-image",
  "quality": "2k"
}

SilicoGrove 文档中的 Gemini 示例就是：

json 复制代码

{
  "model": "gemini-3.1-flash-image",
  "prompt": "一张 16:9 的雨夜霓虹城市图片",
  "size": "1792x1024",
  "quality": "2k",
  "n": 1,
  "response_format": "url"
}

十九、n

例如：

json 复制代码

{
  "n": 1
}

代表：

text 复制代码

生成 1 张图片

文档目前网关层允许：

text 复制代码

1 ~ 128

但这不代表每个上游模型都允许一次生成 128 张。

例如 Gemini 图片模型建议：

json 复制代码

{
  "n": 1
}

其他模型同样可能有自己的更小限制。

因此普通请求建议直接：

text 复制代码

n = 1

二十、response_format

支持：

text 复制代码

url

或者：

text 复制代码

b64_json

例如：

json 复制代码

{
  "response_format": "url"
}

表示希望获得：

json 复制代码

{
  "url": "https://..."
}

如果：

json 复制代码

{
  "response_format": "b64_json"
}

则调用方应做好处理 Base64 图片的准备。

不过 SilicoGrove 本身存在图片持久化逻辑，所以实际返回还会受到网关存储状态影响。

二十一、标准返回结构

推荐调用方定义成：

json 复制代码

{
  "created": 1786192453,
  "data": [
    {
      "url": "https://file.lunadownload.com/temporary/xxx.png",
      "b64_json": null,
      "revised_prompt": null
    }
  ]
}

这里需要注意：

text 复制代码

url

和：

text 复制代码

b64_json

通常不会同时存在。

调用代码最好使用：

text 复制代码

URL 优先
 ↓
Base64 兜底

二十二、revised_prompt 是什么？

部分上游模型可能返回：

json 复制代码

{
  "revised_prompt": "..."
}

表示：

模型实际使用的、经过内部优化或者改写后的 Prompt。

SilicoGrove 会在上游返回该字段时保留它，但不是所有模型都会返回。

因此：

text 复制代码

revised_prompt

属于：

text 复制代码

可选字段

不要强制依赖。

二十三、错误处理

生产代码不要只判断：

text 复制代码

HTTP 200

建议至少处理：

text 复制代码

例如 Python：

python 复制代码

if response.status_code != 200:
    print(
        "请求失败:",
        response.status_code,
        response.text
    )

Go：

go 复制代码

if resp.StatusCode != http.StatusOK {

	fmt.Printf(
		"请求失败 status=%d body=%s\n",
		resp.StatusCode,
		string(body),
	)

	return
}

二十四、推荐的生产调用流程

实际项目最好按下面流程设计：

text 复制代码

业务系统
   │
   ▼
GET /v1/models
   │
   ▼
确认模型可用
   │
   ▼
POST /v1/images/generations
   │
   ▼
等待生成
   │
   ├──────────────┐
   │              │
   ▼              ▼
成功             失败
   │              │
   ▼              ▼
检查 URL       记录 HTTP 状态
   │          + error body
   │
   ▼
下载 / 转存图片

二十五、什么时候不建议使用同步接口？

同步接口：

text 复制代码

POST /v1/images/generations

意味着：

text 复制代码

请求
 ↓
等待模型生成
 ↓
上传图片
 ↓
返回结果

如果生成耗时：

text 复制代码

客户端连接就需要一直保持。

如果中间还有：

text 复制代码

Cloudflare

Nginx

API Gateway

负载均衡

客户端 Timeout

就存在超时风险。

因此 SilicoGrove 还提供了：

text 复制代码

POST /v1/images/tasks

异步生图接口。

二十六、异步生图请求

例如：

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
  }'

成功后不会立刻返回图片。

而是：

json 复制代码

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

HTTP 状态：

text 复制代码

202 Accepted

二十七、查询异步任务

拿到：

text 复制代码

task_0123456789abcdef

以后：

bash 复制代码

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

任务状态可能是：

text 复制代码

queued

processing

completed

failed

SilicoGrove 建议每：

text 复制代码

2 ~ 5 秒

查询一次，不要高频并发轮询。

二十八、异步完成返回

例如：

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"
    }
  ]
}

这时候：

text 复制代码

status = completed

才代表真正生成完成。

然后读取：

text 复制代码

data[0].url

即可。

二十九、同步还是异步？

可以简单这样选：

text 复制代码

简单 Demo
前端 Playground
低并发
快速生图

→ /v1/images/generations

如果：

text 复制代码

生产系统
批量任务
图片生成耗时较长
后端任务
容易遇到 504 / 524

建议：

text 复制代码

/v1/images/tasks

也就是异步模式。

三十、最小接入代码汇总

cURL

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"
  }'

Python

python 复制代码

import requests

response = requests.post(
    "https://ai.silicogrove.com/v1/images/generations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    },
    json={
        "model": "gpt-image-2",
        "prompt": "一只橘猫坐在未来城市楼顶",
        "size": "1024x1024",
        "quality": "high",
        "n": 1,
        "response_format": "url"
    },
    timeout=600
)

print(response.json())

Java

java 复制代码

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(
        "https://ai.silicogrove.com/v1/images/generations"
    ))
    .header(
        "Authorization",
        "Bearer YOUR_API_KEY"
    )
    .header(
        "Content-Type",
        "application/json"
    )
    .POST(
        HttpRequest.BodyPublishers.ofString("""
        {
          "model":"gpt-image-2",
          "prompt":"一只橘猫坐在未来城市楼顶",
          "size":"1024x1024",
          "quality":"high",
          "n":1,
          "response_format":"url"
        }
        """)
    )
    .build();

Go

go 复制代码

payload := []byte(`{
  "model":"gpt-image-2",
  "prompt":"一只橘猫坐在未来城市楼顶",
  "size":"1024x1024",
  "quality":"high",
  "n":1,
  "response_format":"url"
}`)

req, _ := http.NewRequest(
	"POST",
	"https://ai.silicogrove.com/v1/images/generations",
	bytes.NewReader(payload),
)

req.Header.Set(
	"Authorization",
	"Bearer YOUR_API_KEY",
)

req.Header.Set(
	"Content-Type",
	"application/json",
)

最后总结

SilicoGrove 的同步图片生成接口整体遵循 OpenAI Images 兼容风格：

text 复制代码

POST /v1/images/generations

最核心的请求就是：

json 复制代码

{
  "model": "gpt-image-2",
  "prompt": "你想生成什么",
  "size": "1024x1024",
  "quality": "high",
  "n": 1,
  "response_format": "url"
}

成功以后主要读取：

text 复制代码

data[0].url

如果 URL 不存在，则兼容：

text 复制代码

data[0].b64_json

即可。

如果是个人脚本、Demo 或低并发业务，使用：

text 复制代码

/v1/images/generations

已经足够。

如果是正式生产环境、大量图片生成任务，或者经常遇到长时间生成、504、524、客户端 Timeout，则更推荐使用 SilicoGrove 提供的：

text 复制代码

POST /v1/images/tasks

异步任务机制。

这样整个调用流程就会从：

text 复制代码

请求 → 长时间等待 → 返回图片

变成：

text 复制代码

提交任务
   ↓
拿到 task_id
   ↓
后台生成
   ↓
查询状态
   ↓
completed
   ↓
获取 data[].url

对于真正的 AI 图片生成业务来说，这种方式会更加稳定。