图片生成 API 文档

本页按真实调用方式把图片生成分成两类：image2 使用同步 Images API，响应里直接返回图片数据；nano_banana* 和 gpt-image-2* 使用异步任务，先提交到 /v1/videos，再用任务 ID 查询结果。

生图 / 生视频

本页是图片生成文档；视频生成请看视频生成 API 文档。如果你想对照 Apifox 的在线接口目录，可以打开 goswitcher api文档。

基础变量

所有示例都使用 BASE_URL 表示站点根地址，不包含 /v1。切换站点时只改这一行即可。

bash

BASE_URL="https://goswitcher.com"
API_KEY="YOUR_API_KEY"

powershell

$BASE_URL = "https://goswitcher.com"
$API_KEY = "YOUR_API_KEY"

如何选择接口

场景	模式	模型	接口	返回方式
`image2` 文生图 / 带参考图生成	同步	`image2`	`POST /v1/images/generations`	直接返回 `data[0].b64_json`
`image2` 图片编辑	同步	`image2`	`POST /v1/images/edits`	直接返回 `data[0].b64_json`
`nano_banana` 文生图 / 图生图	异步	`nano_banana_2`、`nano_banana_pro-1K`、`nano_banana_pro-2K`、`nano_banana_pro-4K`	`POST /v1/videos`	返回任务 ID，最后用任务查询
`gpt-image-2` 文生图 / 图生图	异步	`gpt-image-2`、`gpt-image-2-2K`、`gpt-image-2-4K`	`POST /v1/videos`	返回任务 ID，最后用任务查询
异步任务查询	公共查询	任务 ID	`GET /v1/videos/{task_id}`	返回任务状态和结果地址

核心区别

异步接口的提交响应只是任务状态，不代表图片已经生成完成。只有任务查询返回 completed 时，才从 url、urls 或 data[].url 读取图片。image2 同步接口不需要任务查询，响应里的 b64_json 就是图片数据。

通用鉴权

Header	必填	说明
`Authorization`	是	`Bearer YOUR_API_KEY`
`Content-Type`	是	JSON 请求使用 `application/json`；文件上传使用 `multipart/form-data`

地址变量

BASE_URL 是站点根地址，例如 https://goswitcher.com。不要把它写成 https://goswitcher.com/v1 后再拼 /v1/videos，否则会变成重复路径。

接口详情

image2 同步生成

image2 使用 OpenAI 兼容 Images API，同步返回结果，不需要任务查询。

项目	文生图 / 带参考图生成	图片编辑
Method	`POST`	`POST`
Path	`/v1/images/generations`	`/v1/images/edits`
JSON 参考图	`image` 支持字符串或字符串数组	`image` 支持字符串或字符串数组
文件上传	不推荐	推荐使用 `multipart/form-data`
返回	`data[0].b64_json`	`data[0].b64_json`

请求参数

参数	类型	必填	说明
`model`	string	是	固定为 `image2`
`prompt`	string	是	图片描述或编辑要求
`size`	string	否	如 `1024x1024`、`1024x1792`、`1792x1024`
`image`	string 或 string[]	否	参考图 URL 或完整 Data URL；图片编辑时通常必填
`n`	integer	否	同步接口会按上游能力返回，不能保证请求多张就一定返回多张

文生图 / 带参考图生成

bash

curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image2",
    "prompt": "参考两张图，生成一张广告主图",
    "size": "1024x1792",
    "image": [
      "https://example.com/reference-1.jpg",
      "https://example.com/reference-2.png"
    ]
  }'

powershell

$body = @{
  model = "image2"
  prompt = "参考两张图，生成一张广告主图"
  size = "1024x1792"
  image = @("https://example.com/reference-1.jpg", "https://example.com/reference-2.png")
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
  -Uri "$BASE_URL/v1/images/generations" `
  -Headers @{ Authorization = "Bearer $API_KEY" } `
  -ContentType "application/json" `
  -Body $body

const response = await fetch(`${BASE_URL}/v1/images/generations`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'image2',
    prompt: '参考两张图，生成一张广告主图',
    size: '1024x1792',
    image: [
      'https://example.com/reference-1.jpg',
      'https://example.com/reference-2.png',
    ],
  }),
})

console.log(await response.json())

const { data } = await axios.post(`${BASE_URL}/v1/images/generations`, {
  model: 'image2',
  prompt: '参考两张图，生成一张广告主图',
  size: '1024x1792',
  image: [
    'https://example.com/reference-1.jpg',
    'https://example.com/reference-2.png',
  ],
}, {
  headers: { Authorization: `Bearer ${API_KEY}` },
})

python

resp = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "image2",
        "prompt": "参考两张图，生成一张广告主图",
        "size": "1024x1792",
        "image": [
            "https://example.com/reference-1.jpg",
            "https://example.com/reference-2.png",
        ],
    },
)
print(resp.json())

body, _ := json.Marshal(map[string]any{
	"model":  "image2",
	"prompt": "参考两张图，生成一张广告主图",
	"size":   "1024x1792",
	"image": []string{
		"https://example.com/reference-1.jpg",
		"https://example.com/reference-2.png",
	},
})
req, _ := http.NewRequest("POST", BASE_URL+"/v1/images/generations", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+API_KEY)
req.Header.Set("Content-Type", "application/json")

java

String json = """
{
  "model": "image2",
  "prompt": "参考两张图，生成一张广告主图",
  "size": "1024x1792",
  "image": ["https://example.com/reference-1.jpg", "https://example.com/reference-2.png"]
}
""";

Request request = new Request.Builder()
    .url(BASE_URL + "/v1/images/generations")
    .addHeader("Authorization", "Bearer " + API_KEY)
    .post(RequestBody.create(json, MediaType.parse("application/json")))
    .build();

csharp

var body = new
{
    model = "image2",
    prompt = "参考两张图，生成一张广告主图",
    size = "1024x1792",
    image = new[] { "https://example.com/reference-1.jpg", "https://example.com/reference-2.png" }
};

var response = await client.PostAsJsonAsync($"{BASE_URL}/v1/images/generations", body);

php

$response = $client->post($BASE_URL . '/v1/images/generations', [
    'headers' => ['Authorization' => 'Bearer ' . $API_KEY],
    'json' => [
        'model' => 'image2',
        'prompt' => '参考两张图，生成一张广告主图',
        'size' => '1024x1792',
        'image' => [
            'https://example.com/reference-1.jpg',
            'https://example.com/reference-2.png',
        ],
    ],
]);

ruby

uri = URI("#{BASE_URL}/v1/images/generations")
req = Net::HTTP::Post.new(uri)
req['Authorization'] = "Bearer #{API_KEY}"
req['Content-Type'] = 'application/json'
req.body = {
  model: 'image2',
  prompt: '参考两张图，生成一张广告主图',
  size: '1024x1792',
  image: ['https://example.com/reference-1.jpg', 'https://example.com/reference-2.png']
}.to_json

图片编辑 / 文件上传

bash

curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  --form 'model="image2"' \
  --form 'prompt="保留主体，把背景改成浅灰色摄影棚风格"' \
  --form 'size="1024x1024"' \
  --form 'image=@"/path/to/example.jpg"'

powershell

# PowerShell 7+ 可直接使用 -Form
Invoke-RestMethod -Method Post `
  -Uri "$BASE_URL/v1/images/edits" `
  -Headers @{ Authorization = "Bearer $API_KEY" } `
  -Form @{
    model = "image2"
    prompt = "保留主体，把背景改成浅灰色摄影棚风格"
    size = "1024x1024"
    image = Get-Item "/path/to/example.jpg"
  }

const form = new FormData()
form.append('model', 'image2')
form.append('prompt', '保留主体，把背景改成浅灰色摄影棚风格')
form.append('size', '1024x1024')
form.append('image', fileInput.files[0])

const response = await fetch(`${BASE_URL}/v1/images/edits`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: form,
})

const form = new FormData()
form.append('model', 'image2')
form.append('prompt', '保留主体，把背景改成浅灰色摄影棚风格')
form.append('size', '1024x1024')
form.append('image', fileInput.files[0])

const { data } = await axios.post(`${BASE_URL}/v1/images/edits`, form, {
  headers: { Authorization: `Bearer ${API_KEY}` },
})

python

with open("/path/to/example.jpg", "rb") as image:
    resp = requests.post(
        f"{BASE_URL}/v1/images/edits",
        headers={"Authorization": f"Bearer {API_KEY}"},
        data={
            "model": "image2",
            "prompt": "保留主体，把背景改成浅灰色摄影棚风格",
            "size": "1024x1024",
        },
        files={"image": ("example.jpg", image, "image/jpeg")},
    )
print(resp.json())

var buf bytes.Buffer
writer := multipart.NewWriter(&buf)
writer.WriteField("model", "image2")
writer.WriteField("prompt", "保留主体，把背景改成浅灰色摄影棚风格")
writer.WriteField("size", "1024x1024")
part, _ := writer.CreateFormFile("image", "example.jpg")
file, _ := os.Open("/path/to/example.jpg")
defer file.Close()
io.Copy(part, file)
writer.Close()

req, _ := http.NewRequest("POST", BASE_URL+"/v1/images/edits", &buf)
req.Header.Set("Authorization", "Bearer "+API_KEY)
req.Header.Set("Content-Type", writer.FormDataContentType())

java

RequestBody body = new MultipartBody.Builder()
    .setType(MultipartBody.FORM)
    .addFormDataPart("model", "image2")
    .addFormDataPart("prompt", "保留主体，把背景改成浅灰色摄影棚风格")
    .addFormDataPart("size", "1024x1024")
    .addFormDataPart("image", "example.jpg",
        RequestBody.create(new File("/path/to/example.jpg"), MediaType.parse("image/jpeg")))
    .build();

Request request = new Request.Builder()
    .url(BASE_URL + "/v1/images/edits")
    .addHeader("Authorization", "Bearer " + API_KEY)
    .post(body)
    .build();

csharp

using var form = new MultipartFormDataContent();
form.Add(new StringContent("image2"), "model");
form.Add(new StringContent("保留主体，把背景改成浅灰色摄影棚风格"), "prompt");
form.Add(new StringContent("1024x1024"), "size");
form.Add(new StreamContent(File.OpenRead("/path/to/example.jpg")), "image", "example.jpg");

var response = await client.PostAsync($"{BASE_URL}/v1/images/edits", form);

php

$response = $client->post($BASE_URL . '/v1/images/edits', [
    'headers' => ['Authorization' => 'Bearer ' . $API_KEY],
    'multipart' => [
        ['name' => 'model', 'contents' => 'image2'],
        ['name' => 'prompt', 'contents' => '保留主体，把背景改成浅灰色摄影棚风格'],
        ['name' => 'size', 'contents' => '1024x1024'],
        ['name' => 'image', 'contents' => fopen('/path/to/example.jpg', 'r'), 'filename' => 'example.jpg'],
    ],
]);

ruby

# Ruby 标准库 multipart 代码较长；实际项目建议使用 multipart-post。
uri = URI("#{BASE_URL}/v1/images/edits")
req = Net::HTTP::Post.new(uri)
req['Authorization'] = "Bearer #{API_KEY}"
# 使用 multipart-post 时，将 model、prompt、size 和 image 文件作为表单字段提交。

image2 同步响应示例

json

{
  "created": 1782108238,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSU..."
    }
  ],
  "usage": {
    "input_tokens": 4,
    "output_tokens": 1105,
    "total_tokens": 1109
  }
}

nano_banana 异步生成

项目	内容
Method	`POST`
Path	`/v1/videos`
Content-Type	`application/json`
返回	任务对象，需要继续查询

请求参数

参数	类型	必填	说明
`model`	string	是	`nano_banana_2`、`nano_banana_pro-1K`、`nano_banana_pro-2K`、`nano_banana_pro-4K`
`prompt`	string	是	图片提示词，建议写清楚主体、场景、风格、比例和文字内容
`aspect_ratio`	string	否	常用值：`auto`、`1:1`、`16:9`、`9:16`
`images`	string[]	否	参考图数组，支持公网图片 URL 或完整 Data URL
`n`	integer	否	当前 switcher 支持 `1` 到 `4`。大于 `1` 时拆成本地批量任务

调用示例

bash

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano_banana_2",
    "prompt": "美丽的日出风景，金色的阳光洒在宁静的湖面上，远处是连绵的山脉",
    "aspect_ratio": "16:9"
  }'

powershell

$body = @{
  model = "nano_banana_2"
  prompt = "美丽的日出风景，金色的阳光洒在宁静的湖面上，远处是连绵的山脉"
  aspect_ratio = "16:9"
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
  -Uri "$BASE_URL/v1/videos" `
  -Headers @{ Authorization = "Bearer $API_KEY" } `
  -ContentType "application/json" `
  -Body $body

const response = await fetch(`${BASE_URL}/v1/videos`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'nano_banana_2',
    prompt: '美丽的日出风景，金色的阳光洒在宁静的湖面上，远处是连绵的山脉',
    aspect_ratio: '16:9',
  }),
})

console.log(await response.json())

import axios from 'axios'

const { data } = await axios.post(`${BASE_URL}/v1/videos`, {
  model: 'nano_banana_2',
  prompt: '美丽的日出风景，金色的阳光洒在宁静的湖面上，远处是连绵的山脉',
  aspect_ratio: '16:9',
}, {
  headers: { Authorization: `Bearer ${API_KEY}` },
})

console.log(data)

python

import requests

resp = requests.post(
    f"{BASE_URL}/v1/videos",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "nano_banana_2",
        "prompt": "美丽的日出风景，金色的阳光洒在宁静的湖面上，远处是连绵的山脉",
        "aspect_ratio": "16:9",
    },
)
print(resp.json())

package main

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

func main() {
	body, _ := json.Marshal(map[string]any{
		"model":        "nano_banana_2",
		"prompt":       "美丽的日出风景，金色的阳光洒在宁静的湖面上，远处是连绵的山脉",
		"aspect_ratio": "16:9",
	})
	req, _ := http.NewRequest("POST", BASE_URL+"/v1/videos", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+API_KEY)
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	fmt.Println(resp.Status)
}

java

OkHttpClient client = new OkHttpClient();

String json = """
{
  "model": "nano_banana_2",
  "prompt": "美丽的日出风景，金色的阳光洒在宁静的湖面上，远处是连绵的山脉",
  "aspect_ratio": "16:9"
}
""";

Request request = new Request.Builder()
    .url(BASE_URL + "/v1/videos")
    .addHeader("Authorization", "Bearer " + API_KEY)
    .post(RequestBody.create(json, MediaType.parse("application/json")))
    .build();

try (Response response = client.newCall(request).execute()) {
    System.out.println(response.body().string());
}

csharp

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", API_KEY);

var body = new
{
    model = "nano_banana_2",
    prompt = "美丽的日出风景，金色的阳光洒在宁静的湖面上，远处是连绵的山脉",
    aspect_ratio = "16:9"
};

var response = await client.PostAsJsonAsync($"{BASE_URL}/v1/videos", body);
Console.WriteLine(await response.Content.ReadAsStringAsync());

php

$client = new \GuzzleHttp\Client();

$response = $client->post($BASE_URL . '/v1/videos', [
    'headers' => ['Authorization' => 'Bearer ' . $API_KEY],
    'json' => [
        'model' => 'nano_banana_2',
        'prompt' => '美丽的日出风景，金色的阳光洒在宁静的湖面上，远处是连绵的山脉',
        'aspect_ratio' => '16:9',
    ],
]);

echo $response->getBody();

ruby

require 'net/http'
require 'json'

uri = URI("#{BASE_URL}/v1/videos")
req = Net::HTTP::Post.new(uri)
req['Authorization'] = "Bearer #{API_KEY}"
req['Content-Type'] = 'application/json'
req.body = {
  model: 'nano_banana_2',
  prompt: '美丽的日出风景，金色的阳光洒在宁静的湖面上，远处是连绵的山脉',
  aspect_ratio: '16:9'
}.to_json

puts Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }.body

Banana 图生图与批量请求体

json

{
  "model": "nano_banana_pro-2K",
  "prompt": "保留主体，把图片转换成电影海报风格",
  "aspect_ratio": "9:16",
  "images": [
    "https://example.com/reference.jpg"
  ]
}

json

{
  "model": "nano_banana_2",
  "prompt": "生成四张不同构图的产品海报",
  "aspect_ratio": "1:1",
  "n": 4
}

gpt-image-2 异步生成

项目	内容
Method	`POST`
Path	`/v1/videos`
Content-Type	`application/json`
返回	任务对象，需要继续查询

请求参数

参数	类型	必填	说明
`model`	string	是	`gpt-image-2`、`gpt-image-2-2K`、`gpt-image-2-4K`
`prompt`	string	是	图片提示词
`aspect_ratio`	string	否	可传固定比例，也可传 `auto` 或不传，让模型根据提示词推断
`images`	string[]	否	参考图数组，支持公网图片 URL 或完整 Data URL
`n`	integer	否	当前 switcher 支持 `1` 到 `4`。大于 `1` 时拆成本地批量任务

调用示例

bash

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "生成一张 16:9 横屏风景图，美丽的日出，金色阳光洒在宁静湖面上，远处连绵山脉",
    "aspect_ratio": "16:9"
  }'

powershell

$body = @{
  model = "gpt-image-2"
  prompt = "生成一张 16:9 横屏风景图，美丽的日出，金色阳光洒在宁静湖面上，远处连绵山脉"
  aspect_ratio = "16:9"
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
  -Uri "$BASE_URL/v1/videos" `
  -Headers @{ Authorization = "Bearer $API_KEY" } `
  -ContentType "application/json" `
  -Body $body

const response = await fetch(`${BASE_URL}/v1/videos`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: '生成一张 16:9 横屏风景图，美丽的日出，金色阳光洒在宁静湖面上，远处连绵山脉',
    aspect_ratio: '16:9',
  }),
})

console.log(await response.json())

import axios from 'axios'

const { data } = await axios.post(`${BASE_URL}/v1/videos`, {
  model: 'gpt-image-2',
  prompt: '生成一张 16:9 横屏风景图，美丽的日出，金色阳光洒在宁静湖面上，远处连绵山脉',
  aspect_ratio: '16:9',
}, {
  headers: { Authorization: `Bearer ${API_KEY}` },
})

console.log(data)

python

import requests

resp = requests.post(
    f"{BASE_URL}/v1/videos",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "gpt-image-2",
        "prompt": "生成一张 16:9 横屏风景图，美丽的日出，金色阳光洒在宁静湖面上，远处连绵山脉",
        "aspect_ratio": "16:9",
    },
)
print(resp.json())

body, _ := json.Marshal(map[string]any{
	"model":        "gpt-image-2",
	"prompt":       "生成一张 16:9 横屏风景图，美丽的日出，金色阳光洒在宁静湖面上，远处连绵山脉",
	"aspect_ratio": "16:9",
})
req, _ := http.NewRequest("POST", BASE_URL+"/v1/videos", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+API_KEY)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

java

String json = """
{
  "model": "gpt-image-2",
  "prompt": "生成一张 16:9 横屏风景图，美丽的日出，金色阳光洒在宁静湖面上，远处连绵山脉",
  "aspect_ratio": "16:9"
}
""";

Request request = new Request.Builder()
    .url(BASE_URL + "/v1/videos")
    .addHeader("Authorization", "Bearer " + API_KEY)
    .post(RequestBody.create(json, MediaType.parse("application/json")))
    .build();

csharp

var body = new
{
    model = "gpt-image-2",
    prompt = "生成一张 16:9 横屏风景图，美丽的日出，金色阳光洒在宁静湖面上，远处连绵山脉",
    aspect_ratio = "16:9"
};

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", API_KEY);
var response = await client.PostAsJsonAsync($"{BASE_URL}/v1/videos", body);

php

$response = $client->post($BASE_URL . '/v1/videos', [
    'headers' => ['Authorization' => 'Bearer ' . $API_KEY],
    'json' => [
        'model' => 'gpt-image-2',
        'prompt' => '生成一张 16:9 横屏风景图，美丽的日出，金色阳光洒在宁静湖面上，远处连绵山脉',
        'aspect_ratio' => '16:9',
    ],
]);

ruby

uri = URI("#{BASE_URL}/v1/videos")
req = Net::HTTP::Post.new(uri)
req['Authorization'] = "Bearer #{API_KEY}"
req['Content-Type'] = 'application/json'
req.body = {
  model: 'gpt-image-2',
  prompt: '生成一张 16:9 横屏风景图，美丽的日出，金色阳光洒在宁静湖面上，远处连绵山脉',
  aspect_ratio: '16:9'
}.to_json

GPT Image 2K / 4K 与参考图请求体

json

{
  "model": "gpt-image-2-4K",
  "prompt": "生成竖屏电商主图，主体清晰，背景简洁",
  "aspect_ratio": "9:16"
}

json

{
  "model": "gpt-image-2",
  "prompt": "将参考图转换成油画风格，保留主体轮廓",
  "aspect_ratio": "1:1",
  "images": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  ]
}

任务查询

项目	内容
Method	`GET`
Path	`/v1/videos/{task_id}`
用途	查询 Banana、GPT Image、视频等异步任务

路径参数

参数	类型	必填	说明
`task_id`	string	是	提交接口返回的 `id`

状态字段

status	客户端处理
`queued`	任务排队中，继续轮询
`processing`	任务处理中，继续轮询
`in_progress`	任务处理中，继续轮询
`completed`	任务完成，从 `url`、`urls` 或 `data[].url` 读取结果
`failed`	任务失败，读取 `error` 或 `error.message`

建议每 3 到 5 秒轮询一次，避免过于频繁。

调用示例

bash

TASK_ID="task_xxxxxxxxxxxxx"

curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

powershell

$TASK_ID = "task_xxxxxxxxxxxxx"

Invoke-RestMethod -Method Get `
  -Uri "$BASE_URL/v1/videos/$TASK_ID" `
  -Headers @{ Authorization = "Bearer $API_KEY" }

const taskId = 'task_xxxxxxxxxxxxx'
const response = await fetch(`${BASE_URL}/v1/videos/${taskId}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
})
console.log(await response.json())

const taskId = 'task_xxxxxxxxxxxxx'
const { data } = await axios.get(`${BASE_URL}/v1/videos/${taskId}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
})
console.log(data)

python

task_id = "task_xxxxxxxxxxxxx"
resp = requests.get(
    f"{BASE_URL}/v1/videos/{task_id}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
print(resp.json())

taskID := "task_xxxxxxxxxxxxx"
req, _ := http.NewRequest("GET", BASE_URL+"/v1/videos/"+taskID, nil)
req.Header.Set("Authorization", "Bearer "+API_KEY)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

java

String taskId = "task_xxxxxxxxxxxxx";
Request request = new Request.Builder()
    .url(BASE_URL + "/v1/videos/" + taskId)
    .addHeader("Authorization", "Bearer " + API_KEY)
    .get()
    .build();

csharp

var taskId = "task_xxxxxxxxxxxxx";
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", API_KEY);
var response = await client.GetAsync($"{BASE_URL}/v1/videos/{taskId}");

php

$taskId = 'task_xxxxxxxxxxxxx';
$response = $client->get($BASE_URL . '/v1/videos/' . $taskId, [
    'headers' => ['Authorization' => 'Bearer ' . $API_KEY],
]);

ruby

task_id = 'task_xxxxxxxxxxxxx'
uri = URI("#{BASE_URL}/v1/videos/#{task_id}")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer #{API_KEY}"

任务响应示例

json

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "image",
  "model": "gpt-image-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1709876543
}

json

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "image",
  "model": "nano_banana_2",
  "status": "completed",
  "progress": 100,
  "created_at": 1709876543,
  "completed_at": 1709876580,
  "url": "https://example.com/images/result.jpg"
}

json

{
  "id": "task_batch_xxxxxxxxxxxxx",
  "object": "image_batch",
  "model": "gpt-image-2",
  "status": "completed",
  "progress": 100,
  "urls": ["https://example.com/images/result-1.jpg"],
  "data": [
    {
      "index": 0,
      "id": "task_a",
      "status": "completed",
      "url": "https://example.com/images/result-1.jpg",
      "image_url": "https://example.com/images/result-1.jpg",
      "error": null
    }
  ]
}

json

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "image",
  "model": "gpt-image-2",
  "status": "failed",
  "progress": 100,
  "created_at": 1709876543,
  "completed_at": 1709876580,
  "error": {
    "message": "上游任务失败原因",
    "code": "upstream_error"
  }
}

常见注意点

BASE_URL 是站点根地址，例如 https://goswitcher.com，不要写成 https://goswitcher.com/v1 后再拼 /v1/videos。
异步接口只要没有 completed 或 failed，就继续轮询任务查询接口。
参考图 URL 必须是服务端能访问的图片直链；内网地址、本地文件路径通常不可用。
image2 同步接口返回图片数据；nano_banana* 和 gpt-image-2* 异步接口先返回任务状态。
n > 1 是 switcher 本地批量任务，查询批量任务时从 urls 或 data[].url 读取结果。
生成结果地址通常有有效期，任务完成后建议尽快下载保存。

图片生成 API 文档 ​

基础变量 ​

如何选择接口 ​

通用鉴权 ​

接口详情 ​

image2 同步生成 ​

请求参数 ​

文生图 / 带参考图生成 ​

图片编辑 / 文件上传 ​

nano_banana 异步生成 ​

请求参数 ​

调用示例 ​

gpt-image-2 异步生成 ​

请求参数 ​

调用示例 ​

任务查询 ​

路径参数 ​

状态字段 ​

调用示例 ​

常见注意点 ​

图片生成 API 文档

基础变量

如何选择接口

通用鉴权

接口详情

image2 同步生成

请求参数

文生图 / 带参考图生成

图片编辑 / 文件上传

nano_banana 异步生成

请求参数

调用示例

gpt-image-2 异步生成

请求参数

调用示例

任务查询

路径参数

状态字段

调用示例

常见注意点