Z-Image Plus API

Name: Z-Image Plus API
SKU: alibaba/z-image-plus/text-to-image
Price: 0.01235 USD
Availability: InStock

di Alibaba

Z-Image in dimensioni personalizzate esatte fino a 1536 px

alibaba/z-image-plus/text-to-image

Crea immagine

Lo chiami con il nome di modello alibaba/z-image-plus/text-to-image su POST /jobs/createTask, da 0,01235 USD.

Nome del modelloalibaba/z-image-plus/text-to-image

EndpointPOST https://api.popnow.ai/api/v1/jobs/createTask

# 1. Create the task. Keep the Idempotency-Key if you retry after a network error.
export IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST https://api.popnow.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
  "model": "alibaba/z-image-plus/text-to-image",
  "input": {
    "prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette"
  }
}'

# 2. Copy data.taskId from the response, then poll until state is succeeded, failed, canceled or expired.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

// Node 18+ (or any runtime with fetch). Keep the API key on your server.
const BASE = "https://api.popnow.ai/api/v1";
const headers = { Authorization: `Bearer ${process.env.POPNOW_API_KEY}` };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function call(path, init = {}) {
  const res = await fetch(BASE + path, { ...init, headers: { ...headers, ...init.headers } });
  const body = await res.json();
  if (body.code !== 200) throw new Error(`${body.code} ${body.msg}`);
  return body.data;
}

const { taskId } = await call("/jobs/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    "model": "alibaba/z-image-plus/text-to-image",
    "input": {
      "prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette"
    }
  }),
});

// Poll with backoff. A finished task may still be copying files: wait while an asset is pending.
let task;
for (let delay = 2000; ; delay = Math.min(delay * 1.5, 15000)) {
  await sleep(delay);
  task = await call(`/jobs/recordInfo?taskId=${taskId}`);
  const copying = (task.output?.assets ?? []).some((a) => a.pending && !a.unavailable);
  if (["succeeded", "failed", "canceled", "expired"].includes(task.state) && !copying) break;
}
if (task.state !== "succeeded") throw new Error(`${task.state}: ${task.errorMessage ?? "no detail"}`);

// Each asset has a signed url (no API key needed) that expires at expiresAt: save the file.
for (const asset of task.output.assets) console.log(asset.url);

import os, time, uuid, requests

BASE = "https://api.popnow.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['POPNOW_API_KEY']}"}


def call(method, path, **kwargs):
    body = requests.request(method, BASE + path, headers={**HEADERS, **kwargs.pop("headers", {})}, timeout=30, **kwargs).json()
    if body["code"] != 200:
        raise RuntimeError(f'{body["code"]} {body["msg"]}')
    return body["data"]


task_id = call(
    "POST",
    "/jobs/createTask",
    headers={"Idempotency-Key": str(uuid.uuid4())},  # reuse it if you retry
    json={
        "model": "alibaba/z-image-plus/text-to-image",
        "input": {
            "prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette"
        }
    },
)["taskId"]

# Poll with backoff. A finished task may still be copying files: wait while an asset is pending.
delay = 2.0
while True:
    time.sleep(delay)
    task = call("GET", "/jobs/recordInfo", params={"taskId": task_id})
    assets = (task.get("output") or {}).get("assets") or []
    copying = any(a.get("pending") and not a.get("unavailable") for a in assets)
    if task["state"] in ("succeeded", "failed", "canceled", "expired") and not copying:
        break
    delay = min(delay * 1.5, 15.0)

if task["state"] != "succeeded":
    raise RuntimeError(f'{task["state"]}: {task.get("errorMessage", "no detail")}')

# Each asset has a signed url (no API key needed) that expires at expiresAt: save the file.
for asset in assets:
    print(asset["url"])

L’input è costruito dallo schema qui sotto, quindi supera la verifica così com’è. Sostituisci prompt e link con i tuoi.

Prezzo

Opzione	USD per immagine
`false`	0,01235 USD
`true`	0,0133 USD

Addebiti in USD · Tutte le opzioni e i prezzi: GET /models/alibaba/z-image-plus/text-to-image

Parametri

Questi campi vengono dallo stesso schema con cui verifichiamo ogni richiesta. I campi non elencati vengono rifiutati.

promptstringObbligatorio
Describe the image to generate.
Intervallo
1 – … chars
widthintegerFacoltativo
Output image width in pixels.
Predefinito
1024
Intervallo
256 – 1536
heightintegerFacoltativo
Output image height in pixels.
Predefinito
1536
Intervallo
256 – 1536
enable_prompt_expansionbooleanFacoltativoCambia il prezzo
Lascia che il modello arricchisca un prompt breve.
Predefinito
false
seedintegerFacoltativo
Lo stesso numero dà un risultato ripetibile.
Intervallo
0 – 2147483647

JSON Schema grezzo

{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer",
      "maximum": 2147483647,
      "minimum": 0,
      "description": "Random seed; zero requests a random seed."
    },
    "width": {
      "type": "integer",
      "default": 1024,
      "maximum": 1536,
      "minimum": 256,
      "description": "Output image width in pixels."
    },
    "height": {
      "type": "integer",
      "default": 1536,
      "maximum": 1536,
      "minimum": 256,
      "description": "Output image height in pixels."
    },
    "prompt": {
      "type": "string",
      "minLength": 1,
      "description": "Describe the image to generate."
    },
    "enable_prompt_expansion": {
      "type": "boolean",
      "default": false,
      "description": "Expand the prompt before generation."
    }
  },
  "additionalProperties": false
}

Risposte, polling e callback

Tutti i modelli funzionano allo stesso modo: crei un task, poi lo interroghi o aspetti la callback.

Prima il prezzo

cURL

curl -X POST https://api.popnow.ai/api/v1/jobs/quote \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "alibaba/z-image-plus/text-to-image",
  "input": {
    "prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette"
  }
}'

Prima di eseguire, invia lo stesso corpo della richiesta a POST /jobs/quote per vedere il costo stimato e quello massimo in USD. Il preventivo non esegue alcuna richiesta né addebita il saldo.

Accettata

HTTP

HTTP/1.1 202 Accepted

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued"
  },
  "request_id": "req_example_create"
}

HTTP 202 indica che la richiesta è stata accettata: il massimo in USD resta riservato fino al conteggio finale. Quando una richiesta viene accettata, riserviamo l’importo massimo del preventivo sul tuo saldo API. Al termine addebitiamo l’uso effettivo, senza superare la riserva, e liberiamo il resto. Se la richiesta fallisce, l’importo riservato viene sbloccato.

Controlla lo stato

cURL

curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

Controlla ogni pochi secondi allungando via via l’intervallo e fermati quando state è succeeded, failed, canceled o expired.

Task completato

JSON

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "alibaba/z-image-plus/text-to-image",
    "state": "succeeded",
    "output": {
      "assets": [
        {
          "url": "https://cdn.popnow.ai/tasks/task_01k3m8x9q2z4v7n5p6r8s0t1w3/output.png?signature=FROM_RESPONSE",
          "expiresAt": "2026-10-17T12:20:00Z",
          "mime": "image/png",
          "width": 1024,
          "height": 1024
        }
      ]
    },
    "settled": true
  },
  "request_id": "req_example_record"
}

Scarica dall’url prima di expiresAt. Ti serve un link nuovo più tardi? Chiedilo con POST /common/download-url.

Verifica una callback

Node.js

import { createHash, createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();
// express.raw keeps the exact bytes that were signed; express.json would not match.
app.post("/hooks/popnow", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-Webhook-Timestamp");
  const signature = req.header("X-Webhook-Signature") ?? "";
  const body = JSON.parse(req.body.toString("utf8"));
  const taskId = body.data?.taskId ?? body.task_id;
  const digest = createHash("sha256").update(req.body).digest("hex");
  const expected = createHmac("sha256", process.env.POPNOW_WEBHOOK_SECRET)
    .update(`${taskId}.${timestamp}.${digest}`)
    .digest("base64");
  const ok = expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  // Check the signature first, then reject anything older than five minutes.
  if (!ok || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.status(401).end();
  res.status(200).end(); // answer fast, then fetch the task and store its files
});

Con callBackUrl impostata ti inviamo il task completato. Verifica la firma sul corpo grezzo prima di fidarti.

Invia un file locale

cURL

curl -X POST https://api.popnow.ai/api/v1/common/upload-url \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contentType": "image/png", "bytes": 482113}'

# PUT the file bytes to data.uploadUrl with every header in data.headers, then commit it:
curl -X POST https://api.popnow.ai/api/v1/files/$FILE_ID/commit \
  -H "Authorization: Bearer $POPNOW_API_KEY"
# The commit returns a popnow://f/... reference. Put it in any image, video or
# audio field of the task input instead of a public https URL.

I link https pubblici funzionano così come sono. I file locali passano prima da upload-url e commit.

Informazioni su Z-Image Plus

Z-Image in dimensioni personalizzate esatte fino a 1536 px.

Lo chiami con il nome di modello alibaba/z-image-plus/text-to-image su POST /jobs/createTask, da 0,01235 USD.

Parametri della richiesta

Parametro	Obbligatorio	Descrizione
`seed`	No	Lo stesso numero dà un risultato ripetibile. ≥ 0 · ≤ 2147483647
`width`	No	Output image width in pixels. ≥ 256 · ≤ 1536 · Predefinito: 1024
`height`	No	Output image height in pixels. ≥ 256 · ≤ 1536 · Predefinito: 1536
`prompt`	Sì	Describe the image to generate.
`enable_prompt_expansion`	No	Lascia che il modello arricchisca un prompt breve. Predefinito: false

Prezzi

I prezzi sono in USD. L’API usa un saldo separato in dollari statunitensi. I crediti del sito non si possono usare per l’API né convertire in saldo API; il saldo API non si può convertire in crediti del sito. Quando una richiesta viene accettata, riserviamo l’importo massimo del preventivo sul tuo saldo API. Al termine addebitiamo l’uso effettivo, senza superare la riserva, e liberiamo il resto. Se la richiesta fallisce, l’importo riservato viene sbloccato.

Opzione	USD per immagine
false	0,01235 USD
true	0,0133 USD

Prima di eseguire, invia lo stesso corpo della richiesta a POST /jobs/quote per vedere il costo stimato e quello massimo in USD. Il preventivo non esegue alcuna richiesta né addebita il saldo.

Guida rapida all'API

Chiama l'API di Z-Image Plus in tre passaggi

Crea una chiave API. Accedi a PopNow e crea una chiave nella console API. Le chiavi iniziano con sk-popnow-. Le chiamate usano il tuo saldo separato in dollari statunitensi.
Invia la richiesta. Invia POST /jobs/createTask con model alibaba/z-image-plus/text-to-image e un oggetto input secondo la tabella dei parametri. La risposta restituisce subito un ID attività.
Recupera il risultato. Interroga GET /jobs/recordInfo con l'ID attività, oppure passa una callBackUrl e ti inviamo lì il risultato. Scarica i link di output quando l'attività riesce.

# 1. Create the task. Keep the Idempotency-Key if you retry after a network error.
export IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST https://api.popnow.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
  "model": "alibaba/z-image-plus/text-to-image",
  "input": {
    "prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette"
  }
}'

# 2. Copy data.taskId from the response, then poll until state is succeeded, failed, canceled or expired.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

Sostituisci il prompt e gli eventuali link con i tuoi. La scheda API contiene il riferimento per risposta, polling e callback.

Domande sull’API di Z-Image Plus

Quanto costa l’API di Z-Image Plus?

Z-Image Plus costa 0,01235 USD per immagine. Prezzi per opzione: false 0,01235 USD per immagine, true 0,0133 USD per immagine. L’API usa un saldo separato in dollari statunitensi. I crediti del sito non si possono usare per l’API né convertire in saldo API; il saldo API non si può convertire in crediti del sito. Quando una richiesta viene accettata, riserviamo l’importo massimo del preventivo sul tuo saldo API. Al termine addebitiamo l’uso effettivo, senza superare la riserva, e liberiamo il resto. Se la richiesta fallisce, l’importo riservato viene sbloccato.

Qual è il nome del modello di Z-Image Plus nell’API?

Inserisci alibaba/z-image-plus/text-to-image per Crea immagine nel campo model di POST /jobs/createTask.

Altro su Z-Image Plus

Documentazione: ID modello e schema di input di Z-Image Plus nella documentazione API Guida rapida all'API di PopNow: la tua prima richiesta in cinque minuti Guida alla generazione di immagini con l'API di PopNow Webhook: ricevi i risultati di Z-Image Plus senza polling