Comment utiliser l’API Z-Image sur PoYo

Mise à jour 2026 : L’API Z-Image sur PoYo coûte 2 crédits par génération, soit environ $0.01. Propulsée par l’architecture S3-DiT d’Alibaba, elle offre une génération d’images rapide pour les workflows de production légers, et ce guide vous explique comment l’intégrer avec l’API PoYo.

Premiers pas avec l’API Z-Image

Étape 1 : Configurer votre compte PoYo

Commencez par créer votre compte PoYo et obtenir vos identifiants API :

Inscrivez-vous sur PoYo.ai
Générez votre clé API dans le tableau de bord
Ajoutez des crédits à votre compte (Z-Image coûte 2 crédits par génération)

Étape 2 : Installer les dépendances requises

# For Node.js/JavaScript
npm install axios

# For Python
pip install requests

# For cURL (no installation needed)

Génération basique de texte vers image

Implémentation JavaScript/Node.js

const axios = require('axios');

const generateImage = async (prompt, size = '1:1') => {
  try {
    const response = await axios.post(
      'https://api.poyo.ai/api/generate/submit',
      {
        model: 'z-image',
        callback_url: 'https://your-domain.com/callback', // Optional webhook
        input: {
          prompt: prompt,
          size: size // Options: '1:1', '4:3', '3:4', '16:9', '9:16'
        }
      },
      {
        headers: {
          'Authorization': `Bearer YOUR_API_KEY`,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Task ID:', response.data.data.task_id);
    console.log('Status:', response.data.data.status);
    console.log('Created:', response.data.data.created_time);
    return response.data.data;
  } catch (error) {
    console.error('Error generating image:', error.response?.data || error.message);
  }
};

// Example usage
generateImage('A futuristic city skyline at sunset with flying cars', '16:9');

Implémentation Python

import requests
import json

def generate_image(prompt, api_key, size='1:1'):
    url = "https://api.poyo.ai/api/generate/submit"

    payload = {
        "model": "z-image",
        "callback_url": "https://your-domain.com/callback",  # Optional webhook
        "input": {
            "prompt": prompt,
            "size": size  # Options: '1:1', '4:3', '3:4', '16:9', '9:16'
        }
    }

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()

        result = response.json()
        print(f"Task ID: {result['data']['task_id']}")
        print(f"Status: {result['data']['status']}")
        print(f"Created: {result['data']['created_time']}")
        return result['data']

    except requests.exceptions.RequestException as e:
        print(f"Error checking status: {e}")
        return None

# Example usage
api_key = "YOUR_API_KEY"
result = generate_image("A serene mountain landscape with crystal clear lake", api_key, '16:9')

Implémentation cURL

curl -X POST "https://api.poyo.ai/api/generate/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "callback_url": "https://your-domain.com/callback",
    "input": {
      "prompt": "A professional headshot of a confident business woman in modern office setting",
      "size": "1:1"
    }
  }'

Paramètres API

Corps de la requête

Paramètre	Type	Requis	Description
`model`	string	Oui	Doit être `"z-image"`
`callback_url`	string	Non	URL du webhook pour les notifications asynchrones
`input.prompt`	string	Oui	Description textuelle (1000 caractères maximum)
`input.size`	string	Oui	Ratio d’aspect : `1:1`, `4:3`, `3:4`, `16:9`, `9:16`

Format de réponse

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "not_started",
    "created_time": "2026-06-12T10:30:00"
  }
}

Guide des ratios d’aspect

Choisissez la taille adaptée à votre cas d’utilisation :

const sizeGuide = {
  '1:1': 'Square - Social media posts, profile images, thumbnails',
  '4:3': 'Landscape - Presentations, web content, traditional photos',
  '3:4': 'Portrait - Mobile content, portrait photography',
  '16:9': 'Widescreen - Video thumbnails, banners, hero images',
  '9:16': 'Vertical - Stories, reels, mobile-first content'
};

// Generate images for different platforms
const generateForPlatform = async (prompt, platform) => {
  const platformSizes = {
    instagram_post: '1:1',
    instagram_story: '9:16',
    youtube_thumbnail: '16:9',
    twitter_header: '16:9',
    linkedin_post: '4:3'
  };

  return generateImage(prompt, platformSizes[platform]);
};

Gestion des résultats avec les webhooks

L’API Z-Image utilise des webhooks pour transmettre les résultats. Configurez un point de terminaison webhook pour recevoir les résultats :

Configuration du point de terminaison webhook

// Express.js webhook handler
const express = require('express');
const app = express();

app.use(express.json());

// Webhook endpoint to receive results
app.post('/webhook/callback', (req, res) => {
  const { task_id, status, files } = req.body;

  console.log(`Task ${task_id} status: ${status}`);

  if (status === 'finished' && files && files.length > 0) {
    console.log('Generated image URL:', files[0].file_url);
    // Process the completed image
    processGeneratedImage(task_id, files[0].file_url);
  } else if (status === 'failed') {
    console.error('Generation failed for task:', task_id);
    handleGenerationError(task_id);
  }

  res.status(200).send('OK');
});

const processGeneratedImage = (taskId, imageUrl) => {
  // Your logic to handle the completed image
  console.log(`Processing image from task ${taskId}: ${imageUrl}`);
};

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Alternative : vérification manuelle du statut

Si vous préférez ne pas utiliser de webhooks, vous pouvez interroger le statut de la tâche :

const checkTaskStatus = async (taskId) => {
  try {
    const response = await axios.get(
      `https://api.poyo.ai/api/generate/status/${taskId}`,
      {
        headers: {
          'Authorization': `Bearer YOUR_API_KEY`
        }
      }
    );

    return response.data.data;
  } catch (error) {
    console.error('Error checking status:', error.message);
    return null;
  }
};

const pollForResult = async (taskId, maxAttempts = 30) => {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const taskData = await checkTaskStatus(taskId);

    if (!taskData) break;

    console.log(`Status: ${taskData.status}`);

    if (taskData.status === 'finished') {
      console.log('Image generated successfully!');
      if (taskData.files && taskData.files.length > 0) {
        console.log('Image URL:', taskData.files[0].file_url);
      }
      return taskData;
    } else if (taskData.status === 'failed') {
      console.error('Generation failed:', taskData.error_message);
      return null;
    }

    // Wait 1 second (Z-Image is fast!)
    await new Promise(resolve => setTimeout(resolve, 1000));
  }

  console.error('Maximum polling attempts reached');
  return null;
};

// Complete workflow example
const completeGeneration = async (prompt, size = '1:1') => {
  // Step 1: Submit generation request
  const generation = await generateImage(prompt, size);

  if (!generation) return null;

  // Step 2: Poll for results
  const result = await pollForResult(generation.task_id);

  return result;
};

Vérification du statut en Python

import time

def check_task_status(task_id, api_key):
    url = f"https://api.poyo.ai/api/generate/status/{task_id}"

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()

        return response.json()['data']
    except requests.exceptions.RequestException as e:
        print(f"Error checking status: {e}")
        return None

def wait_for_completion(task_id, api_key, max_attempts=30):
    for attempt in range(max_attempts):
        task_data = check_task_status(task_id, api_key)

        if not task_data:
            break

        print(f"Status: {task_data['status']}")

        if task_data['status'] == 'finished':
            print("Image generated successfully!")
            if task_data.get('files') and len(task_data['files']) > 0:
                print(f"Image URL: {task_data['files'][0]['file_url']}")
            return task_data
        elif task_data['status'] == 'failed':
            print(f"Generation failed: {task_data.get('error_message', 'Unknown error')}")
            return None

        time.sleep(1)  # Wait 1 second

    print("Maximum attempts reached")
    return None

# Complete workflow
def complete_image_generation(prompt, api_key, size='1:1'):
    # Step 1: Submit request
    task_result = generate_image(prompt, api_key, size)

    if not task_result:
        return None

    # Step 2: Wait for completion
    final_result = wait_for_completion(task_result['task_id'], api_key)

    return final_result

Gestion des erreurs et bonnes pratiques

Gestion complète des erreurs

const robustImageGeneration = async (prompt, size = '1:1', retries = 3) => {
  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      const response = await axios.post(
        'https://api.poyo.ai/api/generate/submit',
        {
          model: 'z-image',
          input: {
            prompt: prompt,
            size: size
          }
        },
        {
          headers: {
            'Authorization': `Bearer YOUR_API_KEY`,
            'Content-Type': 'application/json'
          },
          timeout: 30000 // 30 second timeout
        }
      );

      return response.data.data;

    } catch (error) {
      if (error.response) {
        const status = error.response.status;
        const message = error.response.data?.error || 'Unknown error';

        console.error(`API Error (${status}): ${message}`);

        // Don't retry for certain errors
        if (status === 401 || status === 403) {
          throw new Error('Authentication failed. Check your API key.');
        }

        if (status === 400) {
          throw new Error(`Bad request: ${message}`);
        }

      } else if (error.request) {
        console.error('Network error:', error.message);
      } else {
        console.error('Request setup error:', error.message);
      }

      // If this was the last attempt, throw the error
      if (attempt === retries - 1) {
        throw error;
      }

      // Wait before retrying (exponential backoff)
      const delay = Math.pow(2, attempt) * 1000;
      console.log(`Retrying in ${delay}ms... (Attempt ${attempt + 1}/${retries})`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
};

Bonnes pratiques

Gardez les prompts sous 1000 caractères - Z-Image impose une longueur maximale de prompt
Utilisez des prompts descriptifs - Davantage de détails produisent généralement de meilleurs résultats
Mettez les résultats en cache - Stockez les images générées pour éviter de recréer un contenu identique
Gérez correctement l’asynchrone - Attendez toujours la fin de la tâche avant d’utiliser les résultats

Conseils d’ingénierie des prompts

Structure efficace d’un prompt

// Good prompts for Z-Image
const goodPrompts = [
  // Clear subject + style + details
  "Professional product photo of a sleek smartphone on white background, studio lighting, 4K quality",

  // Scene + atmosphere + composition
  "Cozy coffee shop interior at golden hour, warm lighting, wooden furniture, plants on shelves",

  // Character + action + setting
  "Young woman reading a book in a modern library, natural light from large windows, peaceful atmosphere",

  // Text rendering (Z-Image excels at this)
  "Minimalist poster design with text 'INNOVATION 2026' in bold typography, blue gradient background"
];

// Prompts optimized for bilingual text
const textPrompts = [
  "Store sign with 'OPEN' in English and '营业中' in Chinese, neon style",
  "Business card design with company name 'TechFlow 科技流' in elegant font"
];

Traitement par lots

const generateBatch = async (prompts, size = '1:1') => {
  // Submit all generation requests in parallel
  const generations = await Promise.all(
    prompts.map(prompt => generateImage(prompt, size))
  );

  // Wait for all results
  const results = await Promise.all(
    generations
      .filter(gen => gen !== null)
      .map(gen => pollForResult(gen.task_id))
  );

  return results.filter(result => result !== null);
};

// Example: Generate multiple social media images
const socialMediaPrompts = [
  "Motivational quote background with sunrise",
  "Abstract geometric pattern in blue and purple",
  "Minimalist workspace setup with laptop"
];

const images = await generateBatch(socialMediaPrompts, '1:1');

Conclusion

L’API Z-Image sur PoYo offre une génération d’images ultra-rapide et de haute qualité avec d’excellentes capacités de rendu de texte bilingue. Grâce à son API simple à deux paramètres (prompt et size), vous pouvez intégrer une puissante génération d’images dans vos applications en quelques minutes.

Pour découvrir des fonctionnalités plus avancées et la documentation complète de l’API, consultez la documentation officielle de l’API Z-Image.

Prêt à commencer ? Obtenez votre clé API et commencez à créer avec Z-Image dès aujourd’hui.

Besoin d’aide pour l’implémentation ? Rejoignez notre communauté de développeurs ou consultez davantage de tutoriels API pour découvrir des techniques avancées.

Comment utiliser l’API Z-Image sur PoYo : guide complet pour les développeurs

Table of Contents