API 参考

Base URL

txt

https://api.pixapi.ai

通用 headers

Header	必填	说明
`Authorization`	是	`Bearer $PIXAPI_KEY`
`Content-Type`	是	图片和视频请求使用 `application/json`。

Pixapi 模型请求使用 OpenAI 兼容字段：model、prompt、n、size，以及模型支持的 quality 等控制项。旧图片生成请求格式仅保留在过渡格式中。

同步与异步模式

图片请求支持标准 OpenAI-compatible 同步 endpoint：POST /v1/images/generations 和 POST /v1/images/edits。

耗时图片任务也可以使用 /v1/async/* 下的独立异步 endpoint。视频生成只支持异步创建，必须通过 POST /v1/async/videos/generations 提交。Pixapi 会立即返回任务 id。使用 GET /v1/tasks/{id} 轮询，直到任务进入 completed 或 failed。

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

工作负载	仅异步 endpoint
视频生成	`POST /v1/async/videos/generations`

不要再使用 ?async=true 或 "async": true。完整集成流程见异步媒体任务。

请求示例

bash

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

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"])

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);

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;

图片生成

http

POST /v1/images/generations

使用 OpenAI 兼容请求字段，从提示词生成一张或多张图片。

字段	类型	必填	说明
`model`	string	是	图片模型 id，例如 `gemini-3-pro-image-preview` 或 `gpt-image-2`。Gemini 请求请使用规范的 `gemini-*` 模型 id。
`prompt`	string	是	描述目标图片的文本提示词。
`n`	number	否	返回图片数量，未传时默认 `1`，当前仅支持传 `1`。
`size`	string	否	输出形状。Gemini 图片模型使用 `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16` 或 `16:9` 这类比例值；GPT Image 模型使用 `auto`、预设尺寸或自定义 `WIDTHxHEIGHT` 值。
`quality`	string	否	模型支持时可设置质量档位，例如 `low`、`medium`、`high` 或 `auto`。

图片编辑

http

POST /v1/images/edits

使用 OpenAI 兼容 JSON 字段编辑一张或多张输入图片。image 字段只接受托管图片 URL。

字段	类型	必填	说明
`model`	string	是	支持编辑的图片模型 id，例如 `gemini-3-pro-image-preview` 或 `gpt-image-2`。Gemini 请求请使用规范的 `gemini-*` 模型 id。
`prompt`	string	是	描述编辑意图的文本指令。
`image`	string 或 string[]	是	输入图片 URL；模型支持多参考图时，可发送图片 URL 数组。不支持文件上传或 base64 图片数据。
`n`	number	否	返回图片数量，当前仅支持传 `1`。
`size`	string	否	输出形状。Gemini 图片模型使用 `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16` 或 `16:9` 这类比例值；GPT Image 模型使用 `auto`、预设尺寸或自定义 `WIDTHxHEIGHT` 值。
`quality`	string	否	模型支持时可设置质量档位。

json

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

成功的图片响应使用 OpenAI 图片响应结构：

json

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

图片响应固定在 data[].url 返回生成资源 URL。

异步媒体提交

http

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

以后台任务方式提交耗时媒体请求。异步图片 endpoint 接受与对应图片生成、图片编辑 endpoint 相同的请求字段。视频生成只通过异步视频 endpoint 提供。

视频提交使用 OpenAI 风格 JSON payload：

视频提交使用以下 JSON 字段。

字段	类型	必填	说明
`model`	string	是	视频模型 id，例如 `veo3.1-fast`、`seedance-2`、`kling-3.0-turbo` 或 `wan2.6`。
`prompt`	string	是	描述场景与运动的文本提示。1–2000 字符。
`seconds`	integer	是	时长（秒）。允许值因模型而异（Veo：`4` / `6` / `8`）。
`resolution`	string	否	清晰度档，如 `720p`、`1080p`、`4k`。默认值取决于模型。
`n`	integer	否	输出条数，默认 `1`。
`image`	string \| string[]	否	图生视频时的公网 `http(s)` 图片 URL。
`providerOptions`	object	否	模型扩展参数。允许字段见各模型文档（例如 Veo 的 `aspect_ratio`、Seedance 的 `generate_audio`）。

json

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

字段	说明
`status`	Pixapi 接收任务后返回 `submitted`。
`id`	用于 `GET /v1/tasks/{id}` 的任务 id。
`progress`	`0` 到 `100` 的整数进度。
`created_at`	任务提交时的 Unix 时间戳。
`model`	请求中的模型 id。

媒体任务

http

GET /v1/tasks/{id}

查询异步图片或视频任务。

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
}

字段	说明
`id`	异步创建请求返回的任务 id。
`status`	`submitted`、`processing`、`completed` 或 `failed`。
`credits_cost`	任务完成后扣除的积分。
`model`	任务使用的模型 id。
`progress`	`0` 到 `100` 的整数进度。
`result.type`	输出媒体类型，例如 `image` 或 `video`。
`result.data`	生成媒体列表；可用时每一项包含 `url`。
`created`	任务创建时的 Unix 时间戳。
`completed`	任务完成时的 Unix 时间戳。

错误格式

json

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

模型列表

http

GET /v1/models

返回当前账户可用的模型 id 和能力。

模型列表返回规范模型 id。Gemini 生成和编辑请求优先使用返回的 gemini-* 模型 id。

json

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

GPT Image

API 参考 ​

Base URL ​

通用 headers ​

同步与异步模式 ​

请求示例 ​

图片生成 ​

图片编辑 ​

异步媒体提交 ​

媒体任务 ​

错误格式 ​

模型列表 ​

API 参考

Base URL

通用 headers

同步与异步模式

请求示例

图片生成

图片编辑

异步媒体提交

媒体任务

错误格式

模型列表