Referência da API

URL base

https://api.pixapi.ai

Headers compartilhados

Header	Obrigatório	Descrição
Authorization	Sim	Bearer $PIXAPI_KEY
Content-Type	Sim	Use application/json para requisições de imagem e vídeo.

As requisições de modelo da Pixapi seguem nomes de campos compatíveis com OpenAI. Use model, prompt, n, size e controles opcionais do modelo, como quality. O formato de requisição compatível com Nano Banana mais antigo está documentado apenas em Formato de transição legado.

Modos síncrono e assíncrono

Requisições de imagem suportam os endpoints síncronos padrão compatíveis com OpenAI: POST /v1/images/generations e POST /v1/images/edits.

Trabalhos de imagem mais demorados também podem usar endpoints assíncronos dedicados em /v1/async/*. A geração de vídeo é apenas assíncrona e deve ser enviada por POST /v1/async/videos/generations. A Pixapi retorna um task id imediatamente. Consulte GET /v1/tasks/{id} até que a tarefa chegue a completed ou failed.

Carga de trabalho	Endpoint síncrono	Endpoint assíncrono
Texto para imagem	POST /v1/images/generations	POST /v1/async/images/generations
Edição de imagem	POST /v1/images/edits	POST /v1/async/images/edits

Carga de trabalho	Endpoint apenas assíncrono
Geração de vídeo	POST /v1/async/videos/generations

Não use ?async=true nem "async": true. Consulte Tarefas Assíncronas de Mídia para o padrão completo de integração.

Exemplos de requisição

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

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

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

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

Geração de imagens

POST /v1/images/generations

Gere uma ou mais imagens a partir de um prompt usando campos de requisição compatíveis com OpenAI.

Campo	Tipo	Obrigatório	Descrição
model	string	Sim	ID do modelo de imagem, como gemini-3-pro-image-preview ou gpt-image-2. Use IDs canônicos gemini-* para requisições Gemini.
prompt	string	Sim	Prompt de texto descrevendo a imagem desejada.
n	number	Não	Número de imagens a retornar. O padrão é 1 quando omitido.
size	string	Não	Formato de saída. Modelos de imagem Gemini usam proporções como 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16 ou 16:9; modelos GPT Image usam auto, tamanhos predefinidos ou valores personalizados WIDTHxHEIGHT.
quality	string	Não	Nível de qualidade quando suportado, como low, medium, high ou auto.

Edição de imagens

POST /v1/images/edits

Edite uma ou mais imagens de entrada usando campos JSON compatíveis com OpenAI. O campo image aceita apenas URLs de imagens hospedadas.

Campo	Tipo	Obrigatório	Descrição
model	string	Sim	ID de modelo com suporte a edição, como gemini-3-pro-image-preview ou gpt-image-2. Use IDs canônicos gemini-* para requisições Gemini.
prompt	string	Sim	Instrução de texto descrevendo a edição.
image	string ou string[]	Sim	URL da imagem de entrada. Envie um array de URLs quando o modelo suportar múltiplas referências. Uploads de arquivo e dados base64 não são suportados.
n	number	Não	Número de imagens a retornar.
size	string	Não	Formato de saída. Modelos de imagem Gemini usam proporções como 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16 ou 16:9; modelos GPT Image usam auto, tamanhos predefinidos ou valores personalizados WIDTHxHEIGHT.
quality	string	Não	Nível de qualidade quando suportado.

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

Respostas de imagem bem-sucedidas seguem o formato de imagem da OpenAI:

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

Respostas de imagem sempre retornam URLs dos ativos gerados em data[].url.

Envios assíncronos de mídia

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

Envie trabalhos de mídia de longa duração como tarefa em segundo plano. Endpoints assíncronos de imagem aceitam os mesmos campos dos endpoints correspondentes de geração e edição de imagem. A geração de vídeo está disponível apenas pelo endpoint assíncrono de vídeo.

Envios de vídeo usam um payload JSON no estilo OpenAI:

Campo	Tipo	Obrigatório	Descrição
model	string	Sim	ID do modelo de vídeo, como veo ou wan.
prompt	string	Sim	Prompt de texto descrevendo a cena e o movimento.
duration	number	Não	Duração solicitada do vídeo, em segundos.
size	string	Não	Proporção de saída. Veo usa 16:9 por padrão e suporta 9:16 para vídeo vertical.
input_image	string	Não	URL opcional de imagem de entrada para imagem para vídeo.

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

Campo	Descrição
status	submitted depois que a Pixapi aceita a tarefa.
id	Task id usado com GET /v1/tasks/{id}.
progress	Valor inteiro de progresso de 0 a 100.
created_at	Timestamp Unix do momento em que a tarefa foi enviada.
model	ID do modelo vindo da requisição.

Tarefas de mídia

GET /v1/tasks/{id}

Recupere uma tarefa assíncrona de imagem ou vídeo.

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

Campo	Descrição
id	Task id retornado pela requisição assíncrona de criação.
status	submitted, processing, completed, or failed.
credits_cost	Créditos cobrados após a conclusão da tarefa.
model	ID do modelo usado pela tarefa.
progress	Valor inteiro de progresso de 0 a 100.
result.type	Tipo de mídia de saída, como image ou video.
result.data	Itens de mídia gerados. Cada item inclui uma url quando disponível.
created	Timestamp Unix do momento em que a tarefa foi criada.
completed	Timestamp Unix do momento em que a tarefa foi concluída.

Formato de erro

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

Listar modelos

GET /v1/models

Retorna IDs de modelo e capacidades disponíveis para a conta atual.

Respostas de lista de modelos usam IDs canônicos. Prefira os IDs gemini-* retornados para requisições Gemini de geração e edição.

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