异步媒体任务

图片生成、图片编辑和视频生成都可能超过普通 HTTP 请求的等待时间。图片请求可以使用标准 endpoint 或 /v1/async/* endpoint。视频生成只支持异步创建，必须通过 /v1/async/videos/generations 提交。

Endpoint

工作负载	异步 endpoint
文生图	`POST /v1/async/images/generations`
图片编辑	`POST /v1/async/images/edits`
文生视频或图生视频	`POST /v1/async/videos/generations`

异步图片请求 body 与对应图片 endpoint 保持一致。视频请求直接使用异步视频 endpoint。不要再添加 async=true query 参数或 "async": true body 字段。

提交任务

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

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

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

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": "2048x2048"
  }`)

  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": "2048x2048"
      }
      """;

    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" => "2048x2048",
]);

$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 会在任务提交后立即返回：

json

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

查询任务

使用异步 endpoint 返回的任务 id：

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;

任务完成后，生成媒体会放在 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
}

状态值

状态	含义
`submitted`	Pixapi 已接收任务并进入队列。
`processing`	上游模型正在生成媒体。
`completed`	任务完成，`result` 可用。
`failed`	任务失败，查看 `error` 对象。

错误格式

json

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

集成模式

通过 /v1/async/images/generations、/v1/async/images/edits 或 /v1/async/videos/generations 提交耗时请求。
将返回的 id 保存到你的数据库。
从后端用指数退避轮询 GET /v1/tasks/{id}。
在产品 UI 中展示 status 和 progress。
任务进入 completed 后保存最终的 result.data[] URL。

不要在纯浏览器代码里携带 Pixapi Key 轮询。和生成请求一样，轮询也应通过你的后端转发。

Gemini 图片

GPT Image

异步媒体任务

Endpoint

提交任务

查询任务

状态值

错误格式

集成模式

GPT Image

异步媒体任务 ​

Endpoint ​

提交任务 ​

查询任务 ​

状态值 ​

错误格式 ​

集成模式 ​

异步媒体任务

Endpoint

提交任务

查询任务

状态值

错误格式

集成模式