Tarefas Assíncronas de Mídia

Geração de imagens, edição de imagens e geração de vídeo podem demorar mais do que uma requisição HTTP normal. Requisições de imagem podem usar os endpoints padrão ou endpoints /v1/async/*. A geração de vídeo é apenas assíncrona e deve ser enviada por /v1/async/videos/generations.

Endpoints

Carga de trabalho	Endpoint assíncrono
Texto para imagem	`POST /v1/async/images/generations`
Edição de imagem	`POST /v1/async/images/edits`
Texto para vídeo ou imagem para vídeo	`POST /v1/async/videos/generations`

Os corpos de requisição assíncrona de imagem permanecem iguais aos endpoints de imagem correspondentes. Requisições de vídeo usam diretamente o endpoint assíncrono de vídeo. Não adicione parâmetros de query async=true nem campos de corpo "async": true.

Envie uma tarefa

bash

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

import os
import requests

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

response.raise_for_status()
task = response.json()
print(task["id"])

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

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

const task = await response.json();
console.log(task.id);

package main

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

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

  req, err := http.NewRequest(
    "POST",
    "https://api.pixapi.ai/v1/async/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 PixapiAsyncExample {
  public static void main(String[] args) throws Exception {
    String body = """
      {
        "model": "gemini-3.1-flash-image-preview",
        "prompt": "A cinematic product photo of a ceramic coffee cup",
        "size": "1:1"
      }
      """;

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.pixapi.ai/v1/async/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.1-flash-image-preview",
  "prompt" => "A cinematic product photo of a ceramic coffee cup",
  "size" => "1:1",
]);

$ch = curl_init("https://api.pixapi.ai/v1/async/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;

A Pixapi retorna imediatamente após o envio da tarefa:

json

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

Consulte uma tarefa

Use o task id retornado pelo endpoint assíncrono:

bash

curl --request GET \
  --url 'https://api.pixapi.ai/v1/tasks/task_01KPQ7J7DWB7QZ3WCEK3YVPBRA' \
  --header 'Authorization: Bearer <token>'

import os
import requests

task_id = "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"

response = requests.get(
    f"https://api.pixapi.ai/v1/tasks/{task_id}",
    headers={"Authorization": f"Bearer {os.environ['PIXAPI_KEY']}"},
)

response.raise_for_status()
task = response.json()
print(task["status"])
print(task["progress"])

const taskId = 'task_01KPQ7J7DWB7QZ3WCEK3YVPBRA';

const response = await fetch(`https://api.pixapi.ai/v1/tasks/${taskId}`, {
  headers: {
    Authorization: `Bearer ${process.env.PIXAPI_KEY}`,
  },
});

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

const task = await response.json();
console.log(task.status, task.progress);

package main

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

func main() {
  taskID := "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"

  req, err := http.NewRequest(
    "GET",
    "https://api.pixapi.ai/v1/tasks/"+taskID,
    nil,
  )
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("PIXAPI_KEY"))

  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 PixapiTaskStatus {
  public static void main(String[] args) throws Exception {
    String taskId = "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA";

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.pixapi.ai/v1/tasks/" + taskId))
      .header("Authorization", "Bearer " + System.getenv("PIXAPI_KEY"))
      .GET()
      .build();

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

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

php

<?php
$taskId = "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA";

$ch = curl_init("https://api.pixapi.ai/v1/tasks/" . $taskId);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("PIXAPI_KEY"),
  ],
]);

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

echo $response;

Tarefas concluídas retornam a mídia gerada em result.data[]:

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
}

Valores de status

Status	Significado
`submitted`	A Pixapi aceitou a tarefa e a colocou na fila de processamento.
`processing`	O modelo upstream está gerando mídia.
`completed`	A tarefa foi concluída e `result` está disponível.
`failed`	A tarefa falhou. Leia o objeto `error`.

Formato de erro

json

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

Padrão de integração

Envie requisições de longa duração através de /v1/async/images/generations, /v1/async/images/edits ou /v1/async/videos/generations.
Armazene o id retornado em seu banco de dados.
Consulte GET /v1/tasks/{id} do seu backend com backoff exponencial.
Mostre status e progress na interface do seu produto.
Salve as URLs finais de result.data[] quando a tarefa atingir completed.

Não consulte a partir de código apenas do navegador com sua chave Pixapi. Direcione a consulta através do seu backend, assim como as requisições de geração.

Gemini Image

GPT Image

Tarefas Assíncronas de Mídia

Endpoints

Envie uma tarefa

Consulte uma tarefa

Valores de status

Formato de erro

Padrão de integração

GPT Image

Tarefas Assíncronas de Mídia ​

Endpoints ​

Envie uma tarefa ​

Consulte uma tarefa ​

Valores de status ​

Formato de erro ​

Padrão de integração ​

Tarefas Assíncronas de Mídia

Endpoints

Envie uma tarefa

Consulte uma tarefa

Valores de status

Formato de erro

Padrão de integração