Stosuj te zalecenia, aby budować niezawodne i efektywne integracje.
Wybór trybu żądania
| Tryb | Najlepsze dla | Zalety | Wady |
|---|
| Async (Polling) | Aplikacje klienckie, proste skrypty | Łatwa implementacja | Wymaga logiki pollingu |
| Callback (Webhooks) | Serwery produkcyjne | Real-time, brak pollingu | Wymaga 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 modelu | Początkowe oczekiwanie | Odstęp pollingu | Maks. oczekiwanie |
|---|
| Obraz (szybki) | 5s | 3s | 2 min |
| Obraz (jakość) | 10s | 5s | 3 min |
| Wideo | 60s | 15s | 10 min |
| Audio | 30s | 10s | 5 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ób | Nie 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 pozytywnych | Uż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życia | Zalecany model | Uwagi |
|---|
| Prototypowanie | Nano Banana | Szybka iteracja dla szybkiego feedbacku |
| Jakość produkcyjna | Flux-2 Pro | Zbalansowana wierność i kontrola |
| Jakość premium | Midjourney | Silny styl artystyczny |
| Wideo (krótkie) | Wan 2.5 | Efektywne generowanie krótkich form |
| Wideo (kinowe) | Sora 2 | Najwyż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