Tareas asíncronas de medios

La generación de imágenes, la edición de imágenes y la generación de vídeo pueden tardar más que una petición HTTP normal. Las peticiones de imagen pueden usar los endpoints estándar o los endpoints /v1/async/*. La generación de vídeo es solo asíncrona y debe enviarse a través de /v1/async/videos/generations.

Endpoints

Carga de trabajo	Endpoint asíncrono
Texto a imagen	`POST /v1/async/images/generations`
Edición de imágenes	`POST /v1/async/images/edits`
Texto a vídeo o imagen a vídeo	`POST /v1/async/videos/generations`

Los cuerpos de petición asíncrona de imagen permanecen iguales que los endpoints de imagen correspondientes. Las peticiones de vídeo usan directamente el endpoint asíncrono de vídeo. No añadas parámetros de consulta async=true ni campos de cuerpo "async": true.

Envía una tarea

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;

Pixapi devuelve inmediatamente tras enviar la tarea:

json

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

Consulta una tarea

Usa el ID de tarea devuelto por el endpoint así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;

Las tareas completadas devuelven los medios generados en 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 estado

Estado	Significado
`submitted`	Pixapi aceptó la tarea y la puso en cola para procesamiento.
`processing`	El modelo upstream está generando medios.
`completed`	La tarea se completó y `result` está disponible.
`failed`	La tarea falló. Lee el objeto `error` .

Formato de error

json

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

Patrón de integración

Envía peticiones de larga duración a través de /v1/async/images/generations, /v1/async/images/edits o /v1/async/videos/generations.
Guarda el id devuelto en tu base de datos.
Consulta GET /v1/tasks/{id} desde tu backend con backoff exponencial.
Muestra status y progress en la interfaz de tu producto.
Guarda las URLs finales de result.data[] cuando la tarea alcance completed.

No consultes desde código solo del navegador con tu clave de Pixapi. Redirige las consultas a través de tu backend igual que las peticiones de generación.

Gemini Image

GPT Image

Tareas asíncronas de medios

Endpoints

Envía una tarea

Consulta una tarea

Valores de estado

Formato de error

Patrón de integración

GPT Image

Tareas asíncronas de medios ​

Endpoints ​

Envía una tarea ​

Consulta una tarea ​

Valores de estado ​

Formato de error ​

Patrón de integración ​

Tareas asíncronas de medios

Endpoints

Envía una tarea

Consulta una tarea

Valores de estado

Formato de error

Patrón de integración