Image Generation API

This page separates image generation into two real calling flows: image2 uses the synchronous Images API and returns image data directly; nano_banana* and gpt-image-2* use asynchronous tasks, submitted through /v1/videos and then queried by task ID.

Images / Videos

This page documents image generation. For video generation, see Video Generation API. You can also compare against the online goswitch API docs.

Base Variables

All examples use BASE_URL as the site root. Do not include /v1 in this value. When you switch to another site, only change this variable.

bash

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

powershell

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

Which Endpoint To Use

Scenario	Mode	Model	Endpoint	Result
`image2` generation / reference generation	Sync	`image2`	`POST /v1/images/generations`	Returns `data[0].b64_json` directly
`image2` image edit	Sync	`image2`	`POST /v1/images/edits`	Returns `data[0].b64_json` directly
`nano_banana` text-to-image / image-to-image	Async	`nano_banana_2`, `nano_banana_pro-1K`, `nano_banana_pro-2K`, `nano_banana_pro-4K`	`POST /v1/videos`	Returns a task ID, then use task query at the end
`gpt-image-2` text-to-image / image-to-image	Async	`gpt-image-2`, `gpt-image-2-2K`, `gpt-image-2-4K`	`POST /v1/videos`	Returns a task ID, then use task query at the end
Async task query	Shared query	Task ID	`GET /v1/videos/{task_id}`	Returns task status and result URLs

Core Difference

The asynchronous submit response is only task state. It does not mean the image has finished. Read images only after the task query returns completed, from url, urls, or data[].url. image2 synchronous endpoints do not need task polling because the response contains b64_json.

Authentication

Header	Required	Notes
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	Yes	Use `application/json` for JSON requests; use `multipart/form-data` for file upload requests

Base URL

BASE_URL is the site root, for example https://goswitcher.com. Do not set it to https://goswitcher.com/v1 and then append /v1/videos, or the path will contain /v1 twice.

Endpoint Details

image2 Sync Generation

image2 uses OpenAI-compatible Images API endpoints. It returns synchronously and does not need task polling.

Item	Text-to-image / reference generation	Image edit
Method	`POST`	`POST`
Path	`/v1/images/generations`	`/v1/images/edits`
JSON reference images	`image` supports a string or string array	`image` supports a string or string array
File upload	Not recommended	Recommended with `multipart/form-data`
Result	`data[0].b64_json`	`data[0].b64_json`

Request Parameters

Parameter	Type	Required	Notes
`model`	string	Yes	Fixed as `image2`
`prompt`	string	Yes	Image description or edit instruction
`size`	string	No	For example `1024x1024`, `1024x1792`, `1792x1024`
`image`	string or string[]	No	Reference image URL or full Data URL. Usually required for image edit
`n`	integer	No	The sync endpoint follows upstream capability. Requesting multiple images does not guarantee multiple images will be returned

Text-To-Image / Reference Generation

bash

curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image2",
    "prompt": "Use two reference images to create an advertising hero image",
    "size": "1024x1792",
    "image": [
      "https://example.com/reference-1.jpg",
      "https://example.com/reference-2.png"
    ]
  }'

powershell

$body = @{
  model = "image2"
  prompt = "Use two reference images to create an advertising hero image"
  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: 'Use two reference images to create an advertising hero image',
    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: 'Use two reference images to create an advertising hero image',
  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": "Use two reference images to create an advertising hero image",
        "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": "Use two reference images to create an advertising hero image",
	"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": "Use two reference images to create an advertising hero image",
  "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 = "Use two reference images to create an advertising hero image",
    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' => 'Use two reference images to create an advertising hero image',
        '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: 'Use two reference images to create an advertising hero image',
  size: '1024x1792',
  image: ['https://example.com/reference-1.jpg', 'https://example.com/reference-2.png']
}.to_json

Image Edit / File Upload

bash

curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  --form 'model="image2"' \
  --form 'prompt="Keep the subject and change the background to a light gray studio setup"' \
  --form 'size="1024x1024"' \
  --form 'image=@"/path/to/example.jpg"'

powershell

# PowerShell 7+ supports -Form directly.
Invoke-RestMethod -Method Post `
  -Uri "$BASE_URL/v1/images/edits" `
  -Headers @{ Authorization = "Bearer $API_KEY" } `
  -Form @{
    model = "image2"
    prompt = "Keep the subject and change the background to a light gray studio setup"
    size = "1024x1024"
    image = Get-Item "/path/to/example.jpg"
  }

const form = new FormData()
form.append('model', 'image2')
form.append('prompt', 'Keep the subject and change the background to a light gray studio setup')
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', 'Keep the subject and change the background to a light gray studio setup')
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": "Keep the subject and change the background to a light gray studio setup",
            "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", "Keep the subject and change the background to a light gray studio setup")
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", "Keep the subject and change the background to a light gray studio setup")
    .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("Keep the subject and change the background to a light gray studio setup"), "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' => 'Keep the subject and change the background to a light gray studio setup'],
        ['name' => 'size', 'contents' => '1024x1024'],
        ['name' => 'image', 'contents' => fopen('/path/to/example.jpg', 'r'), 'filename' => 'example.jpg'],
    ],
]);

ruby

# Multipart with only the Ruby standard library is verbose. In real projects,
# use multipart-post and submit model, prompt, size, and the image file as form fields.
uri = URI("#{BASE_URL}/v1/images/edits")
req = Net::HTTP::Post.new(uri)
req['Authorization'] = "Bearer #{API_KEY}"

image2 synchronous response example

json

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

nano_banana Async Generation

Item	Value
Method	`POST`
Path	`/v1/videos`
Content-Type	`application/json`
Result	Task object. Continue with task query

Request Parameters

Parameter	Type	Required	Notes
`model`	string	Yes	`nano_banana_2`, `nano_banana_pro-1K`, `nano_banana_pro-2K`, `nano_banana_pro-4K`
`prompt`	string	Yes	Image prompt. Describe subject, scene, style, aspect ratio, and text content when needed
`aspect_ratio`	string	No	Common values: `auto`, `1:1`, `16:9`, `9:16`
`images`	string[]	No	Reference images. Public image URLs or full Data URLs are supported
`n`	integer	No	Current switcher supports `1` to `4`. Values above `1` create a local batch task

Call Examples

bash

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano_banana_2",
    "prompt": "A beautiful sunrise landscape, golden sunlight over a calm lake, distant mountain range",
    "aspect_ratio": "16:9"
  }'

powershell

$body = @{
  model = "nano_banana_2"
  prompt = "A beautiful sunrise landscape, golden sunlight over a calm lake, distant mountain range"
  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: 'A beautiful sunrise landscape, golden sunlight over a calm lake, distant mountain range',
    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: 'A beautiful sunrise landscape, golden sunlight over a calm lake, distant mountain range',
  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": "A beautiful sunrise landscape, golden sunlight over a calm lake, distant mountain range",
        "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":       "A beautiful sunrise landscape, golden sunlight over a calm lake, distant mountain range",
		"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": "A beautiful sunrise landscape, golden sunlight over a calm lake, distant mountain range",
  "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 = "A beautiful sunrise landscape, golden sunlight over a calm lake, distant mountain range",
    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' => 'A beautiful sunrise landscape, golden sunlight over a calm lake, distant mountain range',
        '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: 'A beautiful sunrise landscape, golden sunlight over a calm lake, distant mountain range',
  aspect_ratio: '16:9'
}.to_json

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

Banana image-to-image and batch request bodies

json

{
  "model": "nano_banana_pro-2K",
  "prompt": "Keep the main subject and turn the image into a cinematic poster",
  "aspect_ratio": "9:16",
  "images": [
    "https://example.com/reference.jpg"
  ]
}

json

{
  "model": "nano_banana_2",
  "prompt": "Create four product posters with different compositions",
  "aspect_ratio": "1:1",
  "n": 4
}

gpt-image-2 Async Generation

Item	Value
Method	`POST`
Path	`/v1/videos`
Content-Type	`application/json`
Result	Task object. Continue with task query

Request Parameters

Parameter	Type	Required	Notes
`model`	string	Yes	`gpt-image-2`, `gpt-image-2-2K`, `gpt-image-2-4K`
`prompt`	string	Yes	Image prompt
`aspect_ratio`	string	No	Use a fixed ratio, `auto`, or omit it and let the model infer from the prompt
`images`	string[]	No	Reference images. Public image URLs or full Data URLs are supported
`n`	integer	No	Current switcher supports `1` to `4`. Values above `1` create a local batch task

Call Examples

bash

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Create a 16:9 landscape image: beautiful sunrise, golden light on a calm lake, distant mountain range",
    "aspect_ratio": "16:9"
  }'

powershell

$body = @{
  model = "gpt-image-2"
  prompt = "Create a 16:9 landscape image: beautiful sunrise, golden light on a calm lake, distant mountain range"
  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: 'Create a 16:9 landscape image: beautiful sunrise, golden light on a calm lake, distant mountain range',
    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: 'Create a 16:9 landscape image: beautiful sunrise, golden light on a calm lake, distant mountain range',
  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": "Create a 16:9 landscape image: beautiful sunrise, golden light on a calm lake, distant mountain range",
        "aspect_ratio": "16:9",
    },
)
print(resp.json())

body, _ := json.Marshal(map[string]any{
	"model":        "gpt-image-2",
	"prompt":       "Create a 16:9 landscape image: beautiful sunrise, golden light on a calm lake, distant mountain range",
	"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": "Create a 16:9 landscape image: beautiful sunrise, golden light on a calm lake, distant mountain range",
  "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 = "Create a 16:9 landscape image: beautiful sunrise, golden light on a calm lake, distant mountain range",
    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' => 'Create a 16:9 landscape image: beautiful sunrise, golden light on a calm lake, distant mountain range',
        '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: 'Create a 16:9 landscape image: beautiful sunrise, golden light on a calm lake, distant mountain range',
  aspect_ratio: '16:9'
}.to_json

GPT Image 2K / 4K and reference-image request bodies

json

{
  "model": "gpt-image-2-4K",
  "prompt": "Create a vertical ecommerce hero image with a clean background and sharp subject",
  "aspect_ratio": "9:16"
}

json

{
  "model": "gpt-image-2",
  "prompt": "Turn the reference image into an oil painting while preserving the subject outline",
  "aspect_ratio": "1:1",
  "images": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  ]
}

Task Query

Item	Value
Method	`GET`
Path	`/v1/videos/{task_id}`
Use	Query Banana, GPT Image, video, and other asynchronous tasks

Path Parameters

Parameter	Type	Required	Notes
`task_id`	string	Yes	The `id` returned by the submit endpoint

Status Fields

status	Client behavior
`queued`	The task is queued. Continue polling
`processing`	The task is processing. Continue polling
`in_progress`	The task is processing. Continue polling
`completed`	The task is complete. Read results from `url`, `urls`, or `data[].url`
`failed`	The task failed. Read `error` or `error.message`

Poll every 3 to 5 seconds to avoid sending too many query requests.

Call Examples

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

Task response examples

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": "Upstream task failed",
    "code": "upstream_error"
  }
}

Common Notes

BASE_URL is the site root, for example https://goswitcher.com; do not set it to https://goswitcher.com/v1 before appending /v1/videos.
For asynchronous endpoints, continue polling until the task reaches completed or failed.
Reference image URLs must be directly reachable by the server. Intranet URLs and local file paths usually cannot be fetched by the server.
image2 synchronous endpoints return image data directly. nano_banana* and gpt-image-2* asynchronous endpoints return task state first.
n > 1 is a switcher local batch task. Query the batch task and read results from urls or data[].url.
Generated result URLs may expire. Download and store results soon after the task completes.

Image Generation API ​

Base Variables ​

Which Endpoint To Use ​

Authentication ​

Endpoint Details ​

image2 Sync Generation ​

Request Parameters ​

Text-To-Image / Reference Generation ​

Image Edit / File Upload ​

nano_banana Async Generation ​

Request Parameters ​

Call Examples ​

gpt-image-2 Async Generation ​

Request Parameters ​

Call Examples ​

Task Query ​

Path Parameters ​

Status Fields ​

Call Examples ​

Common Notes ​

Image Generation API

Base Variables

Which Endpoint To Use

Authentication

Endpoint Details

image2 Sync Generation

Request Parameters

Text-To-Image / Reference Generation

Image Edit / File Upload

nano_banana Async Generation

Request Parameters

Call Examples

gpt-image-2 Async Generation

Request Parameters

Call Examples

Task Query

Path Parameters

Status Fields

Call Examples

Common Notes