Desenvolvimento

Este guia mostra o fluxo padrão compatível com OpenAI para integrar a Pixapi em sua aplicação.

1. Crie uma chave de API

Abra o painel da Pixapi e crie uma chave em Configurações -> Chaves de API. Armazene o valor no ambiente do seu servidor:

PIXAPI_KEY=sk_...

Não exponha esta chave em código do lado do navegador.

2. Escolha um modelo

Comece com um dos IDs de modelo abaixo:

Caso de uso	ID do modelo	Endpoint
Geração e edição rápida de imagens	gemini-2.5-flash-image	/v1/images/generations, /v1/images/edits
Geração de imagens Gemini equilibrada	gemini-3.1-flash-image-preview	/v1/images/generations, /v1/images/edits
Geração de imagens Gemini de alta fidelidade	gemini-3-pro-image-preview	/v1/images/generations, /v1/images/edits
Geração e edição de imagens GPT	gpt-image-2	/v1/images/generations, /v1/images/edits
Geração de vídeo	veo	/v1/async/videos/generations

3. Envie uma 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;

4. Execute requisições longas assincronamente

Para imagens grandes e edições de imagens, use o endpoint assíncrono que corresponde ao endpoint de imagem. A geração de vídeo é apenas assíncrona.

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

A Pixapi retorna um task id com status: "submitted" e progress: 0. Consulte GET /v1/tasks/{id} a partir do seu backend até que a tarefa chegue a completed ou failed. Consulte Tarefas Assíncronas de Mídia para o ciclo completo.

5. Lide com status e erros

Respostas de imagem bem-sucedidas usam payloads data[] no estilo OpenAI. Requisições com falha incluem código de status HTTP, mensagem e tipo de erro legível por máquina.

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

Consulte Erros para a lista de erros comuns.

Para apps voltados ao usuário, direcione error.type === "insufficient_credits" para Créditos ou Cobrança, para que os usuários resolvam o problema sem sair do fluxo do produto.

6. Mantenha chamadas voltadas ao usuário atrás do seu backend

Para aplicativos de navegador, direcione as chamadas da Pixapi através de sua própria rota de API:

Navegador -> Seu backend -> Pixapi

Isso protege sua chave de API e permite adicionar limites de taxa por usuário, logs de uso e validação específica de produto antes de gastar créditos. Revise o saldo e o histórico em Créditos antes do lançamento.