Develop

This guide shows the standard OpenAI-compatible flow for integrating Pixapi into your application.

1. Create an API key

Open the Pixapi dashboard and create a key from Settings -> API Keys. Store the value in your server environment:

PIXAPI_KEY=sk_...

Do not expose this key in browser-side code.

2. Choose a model

Start with one of the model ids below:

Use case	Model id	Endpoint
Fast image generation and editing	gemini-2.5-flash-image (nano-banana alias)	/v1/images/generations, /v1/images/edits
Balanced Gemini image generation	gemini-3.1-flash-image-preview (nano-banana-2 alias)	/v1/images/generations, /v1/images/edits
High-fidelity Gemini image generation	gemini-3-pro-image-preview (nano-banana-pro alias)	/v1/images/generations, /v1/images/edits
GPT image generation and editing	gpt-image-2	/v1/images/generations, /v1/images/edits
Video generation	veo	/v1/async/videos/generations

3. Send a request

cURL

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

Python

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

JavaScript

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);

Go

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;

4. Run long requests asynchronously

For large images and image edits, use the async endpoint that matches the image endpoint. Video generation is async-only.

curl https://api.pixapi.ai/v1/async/images/generations \
  -H "Authorization: Bearer $PIXAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "A cinematic product photo of a ceramic coffee cup",
    "size": "2048x2048"
  }'

Pixapi returns a task id with status: "submitted" and progress: 0. Poll GET /v1/tasks/{id} from your backend until the task reaches completed or failed. See Async Media Tasks for the full lifecycle.

5. Handle status and errors

Successful image responses use OpenAI-style data[] payloads. Failed requests include an HTTP status code, message, and machine-readable error type.

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

See Errors for the common error list.

For user-facing apps, route error.type === "insufficient_credits" to Credits or Billing so users can resolve it without leaving your product flow.

6. Keep user-facing calls behind your backend

For browser apps, route Pixapi calls through your own API route:

Browser -> Your backend -> Pixapi

This protects your API key and lets you add user-level rate limits, usage logs, and product-specific validation before spending credits. Review balance and history in Credits before launch.