API Reference

Base URL

txt

https://api.pixapi.ai

Shared headers

Header	Required	Description
`Authorization`	Yes	`Bearer $PIXAPI_KEY`
`Content-Type`	Yes	Use `application/json` for image and video requests.

Pixapi model requests follow OpenAI-compatible field names. Use model, prompt, n, size, and optional model controls such as quality. The older image-generation 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": "1:1"
  }'

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": "1:1",
    },
)

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: '1:1',
  }),
});

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": "1:1"
  }`)

  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": "1:1"
      }
      """;

    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" => "1:1",
]);

$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`. Use canonical `gemini-*` ids for Gemini requests.
`prompt`	string	Yes	Text prompt describing the desired image.
`n`	number	No	Number of images to return. Defaults to `1` when omitted. Only `1` is currently supported.
`size`	string	No	Output shape. Gemini image models use aspect ratios such as `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, or `16:9`; GPT Image models use `auto`, preset sizes, or custom `WIDTHxHEIGHT` values.
`quality`	string	No	Quality tier when supported, such as `low`, `medium`, `high`, or `auto`.

Image edits

http

POST /v1/images/edits

Edit one or more input images using OpenAI-compatible JSON fields. The image field only accepts hosted image URLs.

Field	Type	Required	Description
`model`	string	Yes	Editing-capable image model id, such as `gemini-3-pro-image-preview` or `gpt-image-2`. Use canonical `gemini-*` ids for Gemini requests.
`prompt`	string	Yes	Text instruction describing the edit.
`image`	string or string[]	Yes	Input image URL. Send an array of image URLs when the model supports multiple references. File uploads and base64 image data are not supported.
`n`	number	No	Number of images to return. Only `1` is currently supported.
`size`	string	No	Output shape. Gemini image models use aspect ratios such as `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, or `16:9`; GPT Image models use `auto`, preset sizes, or custom `WIDTHxHEIGHT` values.
`quality`	string	No	Quality tier when supported.

json

{
  "model": "gemini-3-pro-image-preview",
  "prompt": "Place the product on a warm studio background",
  "image": "https://cdn.example.com/product.png",
  "n": 1,
  "size": "1:1"
}

Successful image responses follow the OpenAI image shape:

json

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

Image responses always return generated asset URLs in data[].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 a JSON payload with these fields.

Field	Type	Required	Description
`model`	string	Yes	Video model id, such as `veo3.1-fast`, `seedance-2`, `kling-3.0-turbo`, or `wan2.6`.
`prompt`	string	Yes	Text prompt describing the scene and motion. 1–2000 characters.
`seconds`	integer	Yes	Duration in seconds. Allowed values are model-specific (Veo: `4` / `6` / `8`).
`resolution`	string	No	Resolution tier such as `720p`, `1080p`, or `4k`. Default depends on the model.
`n`	integer	No	Number of outputs. Default `1`.
`image`	string \| string[]	No	Public `http(s)` image URL for image-to-video.
`providerOptions`	object	No	Model-specific options. See each model page for allowed keys (for example Veo `aspect_ratio`, Seedance `generate_audio`).

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. Prefer the returned gemini-* ids for Gemini generation and edit requests.

json

{
  "object": "list",
  "data": [
    {
      "id": "gemini-3.1-flash-lite-image",
      "object": "model",
      "category": "image",
      "capabilities": ["text-to-image", "image-to-image"]
    },
    {
      "id": "gemini-3-pro-image-preview",
      "object": "model",
      "category": "image",
      "capabilities": ["text-to-image", "image-to-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 ​

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