Pixapi

外观

快速开始 ​

本指南展示如何用 OpenAI 兼容请求格式接入 Pixapi。

1. 创建 API Key ​

打开 Pixapi 控制台，从 Settings -> API Keys 创建密钥，并保存到服务端环境变量：

bash
PIXAPI_KEY=sk_...

不要在浏览器端暴露这个密钥。

2. 选择模型 ​

可以从下面的模型 id 开始：

场景模型 idEndpoint
快速图片生成与编辑gemini-2.5-flash-image（nano-banana 别名）/v1/images/generations, /v1/images/edits
均衡 Gemini 图片生成gemini-3.1-flash-image-preview（nano-banana-2 别名）/v1/images/generations, /v1/images/edits
高质量 Gemini 图片生成gemini-3-pro-image-preview（nano-banana-pro 别名）/v1/images/generations, /v1/images/edits
GPT 图片生成与编辑gpt-image-2/v1/images/generations, /v1/images/edits
视频生成veo/v1/async/videos/generations

3. 发送请求 ​

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": "1024x1024"
  }'
py
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": "1024x1024",
    },
)

response.raise_for_status()
result = response.json()
print(result["data"][0]["url"])
js
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: '1024x1024',
  }),
});

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": "1024x1024"
  }`)

  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": "1024x1024"
      }
      """;

    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" => "1024x1024",
]);

$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. 用异步方式运行耗时请求 ​

对于大尺寸图片和图片编辑，可以使用与图片 endpoint 对应的异步 endpoint。视频生成只支持异步创建。

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

Pixapi 会返回任务 id、status: "submitted" 和 progress: 0。你的后端可以轮询 GET /v1/tasks/{id}，直到任务进入 completed 或 failed。完整生命周期见异步媒体任务。

5. 处理状态和错误 ​

成功图片响应使用 OpenAI 风格的 data[] payload。失败请求包含 HTTP 状态码、错误消息和机器可读错误类型。

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

常见错误见错误码。

面向用户的应用可以把 error.type === "insufficient_credits" 引导到积分或账单，让用户在产品流程内完成处理。

6. 让用户请求经过你的后端 ​

浏览器应用应通过你自己的 API route 调用 Pixapi：

txt
Browser -> Your backend -> Pixapi

这样可以保护 API Key，并在消耗积分前加入用户级限流、用量日志和业务校验。上线前可在积分查看余额和历史。