Z-Image Plus API

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

par Alibaba

Z-Image en tailles personnalisées exactes jusqu’à 1536 px

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

Créer une image

Appelez-le avec le nom de modèle alibaba/z-image-plus/text-to-image sur POST /jobs/createTask, à partir de 0,01235 $US.

Nom du modèlealibaba/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 est construit à partir du schéma ci-dessous : il passe la validation tel quel. Remplacez le prompt et les liens par les vôtres.

Prix

Option	USD par image
`false`	0,01235 $US
`true`	0,0133 $US

Facturation en USD · Toutes les options et leur prix : GET /models/alibaba/z-image-plus/text-to-image

Paramètres

Ces champs viennent du schéma avec lequel nous vérifions chaque requête. Les champs qui n’y figurent pas sont refusés.

promptstringObligatoire
Describe the image to generate.
Plage
1 – … chars
widthintegerFacultatif
Output image width in pixels.
Par défaut
1024
Plage
256 – 1536
heightintegerFacultatif
Output image height in pixels.
Par défaut
1536
Plage
256 – 1536
enable_prompt_expansionbooleanFacultatifModifie le prix
Laisse le modèle enrichir un prompt court.
Par défaut
false
seedintegerFacultatif
Le même nombre donne un résultat reproductible.
Plage
0 – 2147483647

Schéma JSON brut

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

Réponses, interrogation et callbacks

Tous les modèles fonctionnent de la même façon : créez une tâche, puis interrogez-la ou attendez le callback.

Connaître le prix d’abord

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

Avant l’exécution, envoyez le même corps de requête à POST /jobs/quote pour connaître les frais estimés et leur plafond en USD. Le devis ne lance aucune tâche et ne débite pas votre solde.

Acceptée

HTTP

HTTP/1.1 202 Accepted

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

HTTP 202 signifie que la tâche est acceptée : le plafond en USD reste réservé jusqu’au décompte final. À l’acceptation d’une tâche, le montant maximal du devis est réservé sur votre solde API. À la fin, la facturation suit l’usage réel, sans dépasser ce montant, et le reste est libéré. En cas d’échec, le montant réservé est libéré.

Vérifier l’état

cURL

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

Interrogez toutes les quelques secondes en espaçant progressivement, et arrêtez dès que state vaut succeeded, failed, canceled ou expired.

Tâche terminée

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

Téléchargez depuis l’url avant expiresAt. Besoin d’un nouveau lien plus tard ? Demandez-le à POST /common/download-url.

Vérifier un 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
});

Avec une callBackUrl, nous vous envoyons la tâche terminée. Vérifiez la signature sur le corps brut avant de lui faire confiance.

Envoyer un fichier local

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.

Les liens https publics fonctionnent tels quels. Les fichiers locaux passent d’abord par upload-url et commit.

À propos de Z-Image Plus

Z-Image en tailles personnalisées exactes jusqu’à 1536 px.

Appelez-le avec le nom de modèle alibaba/z-image-plus/text-to-image sur POST /jobs/createTask, à partir de 0,01235 $US.

Paramètres de requête

Paramètre	Requis	Description
`seed`	Non	Le même nombre donne un résultat reproductible. ≥ 0 · ≤ 2147483647
`width`	Non	Output image width in pixels. ≥ 256 · ≤ 1536 · Par défaut: 1024
`height`	Non	Output image height in pixels. ≥ 256 · ≤ 1536 · Par défaut: 1536
`prompt`	Oui	Describe the image to generate.
`enable_prompt_expansion`	Non	Laisse le modèle enrichir un prompt court. Par défaut: false

Tarifs

Les prix sont en USD. L’API utilise un solde distinct en dollars américains. Les crédits du site ne peuvent pas être utilisés pour l’API ni convertis en solde API, et le solde API ne peut pas être converti en crédits du site. À l’acceptation d’une tâche, le montant maximal du devis est réservé sur votre solde API. À la fin, la facturation suit l’usage réel, sans dépasser ce montant, et le reste est libéré. En cas d’échec, le montant réservé est libéré.

Option	USD par image
false	0,01235 $US
true	0,0133 $US

Avant l’exécution, envoyez le même corps de requête à POST /jobs/quote pour connaître les frais estimés et leur plafond en USD. Le devis ne lance aucune tâche et ne débite pas votre solde.

Démarrage rapide de l'API

Appeler l’API Z-Image Plus en trois étapes

Créer une clé API. Connectez-vous à PopNow et créez une clé dans la console API. Les clés commencent par sk-popnow-. Les appels API utilisent votre solde distinct en dollars américains.
Envoyer la requête. Envoyez POST /jobs/createTask avec model alibaba/z-image-plus/text-to-image et un objet input conforme au tableau des paramètres. La réponse renvoie aussitôt un ID de tâche.
Récupérer le résultat. Interrogez GET /jobs/recordInfo avec l’ID de tâche, ou passez une callBackUrl et nous y envoyons le résultat. Téléchargez les liens de sortie quand la tâche réussit.

# 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"

Remplacez le prompt et les liens par les vôtres. L'onglet API contient la référence pour la réponse, le polling et le callback.

Questions sur l’API Z-Image Plus

Combien coûte l’API Z-Image Plus ?

Z-Image Plus coûte 0,01235 $US par image. Prix par option : false 0,01235 $US par image, true 0,0133 $US par image. L’API utilise un solde distinct en dollars américains. Les crédits du site ne peuvent pas être utilisés pour l’API ni convertis en solde API, et le solde API ne peut pas être converti en crédits du site. À l’acceptation d’une tâche, le montant maximal du devis est réservé sur votre solde API. À la fin, la facturation suit l’usage réel, sans dépasser ce montant, et le reste est libéré. En cas d’échec, le montant réservé est libéré.

Quel est le nom de modèle de Z-Image Plus dans l’API ?

Indiquez alibaba/z-image-plus/text-to-image pour Créer une image dans le champ model de POST /jobs/createTask.

En savoir plus sur Z-Image Plus

Docs: ID de modèle et schéma d’entrée de Z-Image Plus dans la doc API Démarrage rapide de l’API PopNow : votre première requête en cinq minutes Guide de génération d’images avec l’API PopNow Webhooks : recevez les résultats de Z-Image Plus sans polling