Przejdź do głównej treści
Stosuj te zalecenia, aby budować niezawodne i efektywne integracje.

Wybór trybu żądania

TrybNajlepsze dlaZaletyWady
Async (Polling)Aplikacje klienckie, proste skryptyŁatwa implementacjaWymaga logiki pollingu
Callback (Webhooks)Serwery produkcyjneReal-time, brak pollinguWymaga publicznego endpointu
Zacznij od trybu async do rozwoju, przełącz na callback w produkcji.

Strategia pollingu

W trybie async zaimplementuj inteligentny polling, aby zbalansować responsywność i wydajność.

Zalecane odstępy

Typ modeluPoczątkowe oczekiwanieOdstęp pollinguMaks. oczekiwanie
Obraz (szybki)5s3s2 min
Obraz (jakość)10s5s3 min
Wideo60s15s10 min
Audio30s10s5 min

Exponential backoff

async function pollWithBackoff(model, taskId, apiKey) {
  let interval = 3000; // Start at 3s
  const maxInterval = 30000; // Max 30s
  const maxAttempts = 60;
  
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.apixo.ai/api/v1/statusTask/${model}?taskId=${taskId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    
    const { data } = await response.json();
    
    if (data.state === 'success') {
      return JSON.parse(data.resultJson).resultUrls;
    }
    if (data.state === 'failed') {
      throw new Error(data.failMsg);
    }
    
    await new Promise(r => setTimeout(r, interval));
    interval = Math.min(interval * 1.5, maxInterval);
  }
  
  throw new Error('Timeout');
}

Obsługa błędów

Zawsze obsługuj niepowodzenia

const result = await pollForResult(taskId);

if (!result) {
  // Handle null/undefined
}

// Check for specific error codes
if (result.state === 'failed') {
  switch (result.failCode) {
    case 'CONTENT_VIOLATION':
      // Prompt needs modification
      break;
    case 'PROCESSING_TIMEOUT':
      // Retry the request
      break;
    case 'INSUFFICIENT_CREDITS':
      // Alert user to add credits
      break;
  }
}

Implementuj ponowienia

async function generateWithRetry(params, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await generateImage(params);
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      
      // Only retry on transient errors
      if (error.failCode === 'PROCESSING_TIMEOUT') {
        await new Promise(r => setTimeout(r, 5000));
        continue;
      }
      
      throw error; // Don't retry content violations etc.
    }
  }
}

Inżynieria promptów

Wskazówki dla generowania obrazów

RóbNie rób
Bądź konkretny: „Szczeniak golden retriever bawiący się w jesiennych liściach”Bądź ogólnikowy: „Pies”
Uwzględnij styl: „akwarela, miękkie światło”Zakładaj domyślne
Określ kompozycję: „portret zbliżony, wycentrowany”Zostaw kompozycję przypadkowi
Używaj opisów pozytywnychUżywaj negatywów typu „bez tła”

Skuteczna struktura promptu

[Temat] + [Akcja/Poza] + [Środowisko] + [Styl] + [Szczegóły techniczne]
Przykład:
Młoda kobieta czytająca książkę w przytulnej kawiarni, 
ciepłe popołudniowe słońce przez okna, 
styl impresjonistyczny olej, 
miękki focus tła, oświetlenie złotej godziny

Zarządzanie zasobami

Pobieraj wyniki niezwłocznie

// Result URLs expire after 24 hours
const urls = await generateImage(prompt);

// Download immediately
for (const url of urls) {
  const response = await fetch(url);
  const buffer = await response.arrayBuffer();
  // Save to your storage
}

Zapisuj ID zadań

// Log task IDs for debugging
console.log(`Task submitted: ${taskId}`);

// Store in database for reference
await db.tasks.create({
  taskId,
  userId: user.id,
  model,
  prompt,
  status: 'pending',
  createdAt: new Date(),
});

Optymalizacja kosztów

Wybierz właściwy model

Przypadek użyciaZalecany modelUwagi
PrototypowanieNano BananaSzybka iteracja dla szybkiego feedbacku
Jakość produkcyjnaFlux-2 ProZbalansowana wierność i kontrola
Jakość premiumMidjourneySilny styl artystyczny
Wideo (krótkie)Wan 2.5Efektywne generowanie krótkich form
Wideo (kinowe)Sora 2Najwyższa jakość wideo
Aktualne ceny zawsze sprawdzaj na stronie Cennik.

Grupuj podobne żądania

Przy generowaniu wielu wariantów używaj trybu image-to-image zamiast generowania od zera za każdym razem.

Monitoruj użycie

// Track costs per user/project
await db.usage.create({
  userId: user.id,
  model,
  cost: MODEL_COSTS[model],
  timestamp: new Date(),
});

// Set up alerts for unusual usage
if (dailyCost > threshold) {
  sendAlert('High API usage detected');
}

Bezpieczeństwo

Chroń klucz API

// DO: Use environment variables
const apiKey = process.env.APIXO_API_KEY;

// DON'T: Hardcode in source
const apiKey = 'sk-abc123'; // Never do this!

// DON'T: Expose in client-side code
// API calls should go through your backend

Waliduj dane użytkownika

function validatePrompt(prompt) {
  if (!prompt || typeof prompt !== 'string') {
    throw new Error('Invalid prompt');
  }
  
  if (prompt.length > 5000) {
    throw new Error('Prompt too long');
  }
  
  // Sanitize before sending to API
  return prompt.trim();
}

Wydajność

Używaj puli połączeń

// Reuse HTTP connections
const agent = new https.Agent({ keepAlive: true });

const response = await fetch(url, {
  agent,
  // ...
});

Równoległość gdy możliwa

// Generate multiple images in parallel
const prompts = ['prompt1', 'prompt2', 'prompt3'];

const tasks = await Promise.all(
  prompts.map(prompt => submitTask(prompt))
);

const results = await Promise.all(
  tasks.map(task => pollForResult(task.taskId))
);

Monitorowanie

Loguj wywołania API

const startTime = Date.now();

try {
  const result = await generateImage(prompt);
  
  logger.info('Generation successful', {
    taskId: result.taskId,
    duration: Date.now() - startTime,
    model,
  });
} catch (error) {
  logger.error('Generation failed', {
    error: error.message,
    duration: Date.now() - startTime,
    model,
  });
}

Konfiguruj alerty

Monitoruj:
  • Wysoki wskaźnik błędów
  • Nietypowe opóźnienia
  • Skoki kosztów
  • Trafienia limitów rate