API Reference

Base URL

txt

https://api.pixapi.ai

Shared headers

Header	Required	Description
`Authorization`	Yes	`Bearer $PIXAPI_KEY`
`Content-Type`	Yes for JSON bodies	Use `application/json` for generation requests. Use `multipart/form-data` for image edits with file uploads.

Pixapi model requests follow OpenAI-compatible field names. Use model, prompt, n, size, and optional model controls such as quality. The older Nano Banana-compatible request format is documented only in Legacy transition format.

Synchronous and async modes

Image requests support the standard OpenAI-compatible synchronous endpoints: POST /v1/images/generations and POST /v1/images/edits.

Long-running image work can also use dedicated async endpoints under /v1/async/*. Video generation is async-only and must be submitted through POST /v1/async/videos/generations. Pixapi returns a task id immediately. Poll GET /v1/tasks/{id} until the task reaches completed or failed.

Workload	Synchronous endpoint	Async endpoint
Text-to-image	`POST /v1/images/generations`	`POST /v1/async/images/generations`
Image editing	`POST /v1/images/edits`	`POST /v1/async/images/edits`

Workload	Async-only endpoint
Video generation	`POST /v1/async/videos/generations`

Do not use ?async=true or "async": true. See Async Media Tasks for the full integration pattern.

Request examples

bash

curl https://api.pixapi.ai/v1/images/generations \
  -H "Authorization: Bearer $PIXAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A cinematic product photo of a ceramic coffee cup",
    "n": 1,
    "size": "1024x1024"
  }'

import os
import requests

response = requests.post(
    "https://api.pixapi.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['PIXAPI_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gemini-3-pro-image-preview",
        "prompt": "A cinematic product photo of a ceramic coffee cup",
        "n": 1,
        "size": "1024x1024",
    },
)

response.raise_for_status()
result = response.json()
print(result["data"][0]["url"])

const response = await fetch('https://api.pixapi.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PIXAPI_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gemini-3-pro-image-preview',
    prompt: 'A cinematic product photo of a ceramic coffee cup',
    n: 1,
    size: '1024x1024',
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const result = await response.json();
console.log(result.data?.[0]?.url ?? result);

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  body := []byte(`{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A cinematic product photo of a ceramic coffee cup",
    "n": 1,
    "size": "1024x1024"
  }`)

  req, err := http.NewRequest(
    "POST",
    "https://api.pixapi.ai/v1/images/generations",
    bytes.NewBuffer(body),
  )
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("PIXAPI_KEY"))
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  result, _ := io.ReadAll(resp.Body)
  fmt.Println(string(result))
}

java

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

class PixapiExample {
  public static void main(String[] args) throws Exception {
    String body = """
      {
        "model": "gemini-3-pro-image-preview",
        "prompt": "A cinematic product photo of a ceramic coffee cup",
        "n": 1,
        "size": "1024x1024"
      }
      """;

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.pixapi.ai/v1/images/generations"))
      .header("Authorization", "Bearer " + System.getenv("PIXAPI_KEY"))
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(body))
      .build();

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

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

php

<?php
$payload = json_encode([
  "model" => "gemini-3-pro-image-preview",
  "prompt" => "A cinematic product photo of a ceramic coffee cup",
  "n" => 1,
  "size" => "1024x1024",
]);

$ch = curl_init("https://api.pixapi.ai/v1/images/generations");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("PIXAPI_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Image generations

http

POST /v1/images/generations

Generate one or more images from a prompt using OpenAI-compatible request fields.

Field	Type	Required	Description
`model`	string	Yes	Image model id, such as `gemini-3-pro-image-preview` or `gpt-image-2`. Supported aliases such as `nano-banana`, `nano-banana-2`, and `nano-banana-pro` are accepted.
`prompt`	string	Yes	Text prompt describing the desired image.
`n`	number	No	Number of images to return. Defaults to `1` when omitted.
`size`	string	No	Output size such as `auto`, `1024x1024`, `1536x1024`, `1024x1536`, or another model-supported `WIDTHxHEIGHT` value.
`quality`	string	No	Quality tier when supported, such as `low`, `medium`, `high`, or `auto`.
`response_format`	string	No	`url` or `b64_json` when supported by the selected model.

Image edits

http

POST /v1/images/edits

Edit one or more input images using OpenAI-compatible multipart form fields.

Field	Type	Required	Description
`model`	string	Yes	Editing-capable image model id, such as `gemini-3-pro-image-preview` or `gpt-image-2`. Supported aliases such as `nano-banana`, `nano-banana-2`, and `nano-banana-pro` are accepted.
`prompt`	string	Yes	Text instruction describing the edit.
`image`	file or file[]	Yes	Input image file. Send multiple `image` fields when the model supports multiple references.
`n`	number	No	Number of images to return.
`size`	string	No	Output size such as `1024x1024` or `auto`.
`quality`	string	No	Quality tier when supported.
`response_format`	string	No	`url` or `b64_json` when supported.

bash

curl https://api.pixapi.ai/v1/images/edits \
  -H "Authorization: Bearer $PIXAPI_KEY" \
  -F "model=gemini-3-pro-image-preview" \
  -F "prompt=Place the product on a warm studio background" \
  -F "image=@product.png" \
  -F "n=1" \
  -F "size=1024x1024"

Successful image responses follow the OpenAI image shape:

json

{
  "created": 1766880000,
  "data": [
    {
      "url": "https://cdn.pixapi.ai/generated/image.png"
    }
  ]
}

When response_format is b64_json, each item contains b64_json instead of url.

Async media submissions

http

POST /v1/async/images/generations
POST /v1/async/images/edits
POST /v1/async/videos/generations

Submit long-running media work as a background task. Async image endpoints accept the same request fields as the matching image generation and edit endpoints. Video generation is only available through the async video endpoint.

Video submissions use an OpenAI-style JSON payload:

Field	Type	Required	Description
`model`	string	Yes	Video model id, such as `veo` or `wan`.
`prompt`	string	Yes	Text prompt describing the scene and motion.
`duration`	number	No	Requested video duration in seconds.
`size`	string	No	Output size or ratio preset such as `1280x720`, `720x1280`, or `16:9`.
`input_image`	string	No	Optional input image URL for image-to-video.

json

{
  "status": "submitted",
  "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
  "progress": 0,
  "created_at": 1703884800,
  "model": "gemini-3.1-flash-image-preview"
}

Field	Description
`status`	`submitted` after Pixapi accepts the task.
`id`	Task id used with `GET /v1/tasks/{id}`.
`progress`	Integer progress value from `0` to `100`.
`created_at`	Unix timestamp for when the task was submitted.
`model`	Model id from the request.

Media tasks

http

GET /v1/tasks/{id}

Retrieve an asynchronous image or video task.

json

{
  "id": "xxx",
  "status": "completed",
  "credits_cost": 1.5,
  "model": "sora-2",
  "progress": 100,
  "result": {
    "type": "video",
    "data": [
      {
        "url": "https://xxx.xxx"
      }
    ]
  },
  "created": 1763088289,
  "completed": 1763088308
}

Field	Description
`id`	Task id returned by the async creation request.
`status`	`submitted`, `processing`, `completed`, or `failed`.
`credits_cost`	Credits charged after task completion.
`model`	Model id used by the task.
`progress`	Integer progress value from `0` to `100`.
`result.type`	Output media type, such as `image` or `video`.
`result.data`	Generated media items. Each item includes a `url` when available.
`created`	Unix timestamp for when the task was created.
`completed`	Unix timestamp for when the task completed.

Error format

json

{
  "error": {
    "code": 400,
    "message": "xxx",
    "type": "invalid_request_error"
  }
}

List models

http

GET /v1/models

Returns model ids and capabilities available for the current account.

Model list responses use canonical model ids. Alias ids such as nano-banana-2 can still be used in generation and edit requests when documented by a model page.

json

{
  "object": "list",
  "data": [
    {
      "id": "gemini-3-pro-image-preview",
      "object": "model",
      "category": "image",
      "capabilities": ["text-to-image", "image-to-image"]
    }
  ]
}

Gemini Image

GPT Image

API Reference

Base URL

Shared headers

Synchronous and async modes

Request examples

Image generations

Image edits

Async media submissions

Media tasks

Error format

List models

GPT Image

API Reference ​

Base URL ​

Shared headers ​

Synchronous and async modes ​

Request examples ​

Image generations ​

Image edits ​

Async media submissions ​

Media tasks ​

Error format ​

List models ​

API Reference

Base URL

Shared headers

Synchronous and async modes

Request examples

Image generations

Image edits

Async media submissions

Media tasks

Error format

List models