Odbieraj wyniki zadań przez callbacki HTTP zamiast pollingu.
Przegląd
W trybie callback APIXO wysyła żądanie POST na podany URL po zakończeniu zadania. Eliminuje to narzut pollingu i zapewnia natychmiastowe powiadomienia — idealne dla aplikacji produkcyjnych o wysokim ruchu.
Konfiguracja
Utwórz endpoint webhooka
Twój endpoint musi akceptować żądania POST, odpowiadać kodem HTTP 200 w ciągu 30 sekund i być publicznie dostępny przez HTTPS.Jeśli endpoint nie odpowie kodem HTTP 200 w ciągu 30 sekund, APIXO ponowi dostawę do 3 razy ze zwiększonymi opóźnieniami.
Express.js
FastAPI
Next.js
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhook/apixo', (req, res) => {
const { taskId, state, resultJson, failCode, failMsg } = req.body.data;
if (state === 'success') {
const urls = JSON.parse(resultJson).resultUrls;
console.log('Generated:', urls);
} else if (state === 'failed') {
console.error(`Task ${taskId} failed: ${failCode} - ${failMsg}`);
}
res.status(200).send('OK');
});
app.listen(3000);
from fastapi import FastAPI, Request
import json
app = FastAPI()
@app.post('/webhook/apixo')
async def handle_webhook(request: Request):
body = await request.json()
data = body['data']
if data['state'] == 'success':
urls = json.loads(data['resultJson'])['resultUrls']
print(f"Generated: {urls}")
elif data['state'] == 'failed':
print(f"Task {data['taskId']} failed: {data['failCode']} - {data['failMsg']}")
return {'status': 'ok'}
// app/api/webhook/apixo/route.ts
import { NextRequest, NextResponse } from 'next/server';
export async function POST(request: NextRequest) {
const body = await request.json();
const { taskId, state, resultJson, failCode, failMsg } = body.data;
if (state === 'success') {
const urls = JSON.parse(resultJson).resultUrls;
console.log('Generated:', urls);
} else if (state === 'failed') {
console.error(`Task ${taskId} failed: ${failCode} - ${failMsg}`);
}
return NextResponse.json({ status: 'ok' });
}
Zgłoś zadanie z callbackiem
Dodaj request_type: "callback" i swój callback_url do żądania:curl -X POST https://api.apixo.ai/api/v1/generateTask/nano-banana \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "callback",
"callback_url": "https://your-domain.com/webhook/apixo",
"input": {
"mode": "text-to-image",
"prompt": "A beautiful landscape"
}
}'
const response = await fetch('https://api.apixo.ai/api/v1/generateTask/nano-banana', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
request_type: 'callback',
callback_url: 'https://your-domain.com/webhook/apixo',
input: {
mode: 'text-to-image',
prompt: 'A beautiful landscape',
},
}),
});
response = requests.post(
'https://api.apixo.ai/api/v1/generateTask/nano-banana',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'request_type': 'callback',
'callback_url': 'https://your-domain.com/webhook/apixo',
'input': {
'mode': 'text-to-image',
'prompt': 'A beautiful landscape',
},
}
)
Payload webhooka
Sukces
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_abc123xyz",
"state": "success",
"resultJson": "{\"resultUrls\":[\"https://cdn.apixo.ai/output/abc.jpg\"]}",
"costTime": 12500,
"createTime": 1704067200000,
"completeTime": 1704067212500
}
}
Błąd
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_abc123xyz",
"state": "failed",
"failCode": "CONTENT_VIOLATION",
"failMsg": "Content violates usage policy",
"createTime": 1704067200000,
"completeTime": 1704067205000
}
}
Pola payloadu
Unikalny identyfikator zadania.
Końcowy stan zadania: success lub failed.
Ciąg JSON zawierający tablicę resultUrls. Obecny przy sukcesie.
Czas przetwarzania w milisekundach.
Kod błędu. Obecny przy błędzie.
Czytelna wiadomość błędu. Obecna przy błędzie.
Polityka ponawiania
Jeśli endpoint webhooka nie odpowie kodem HTTP 200:
| Próba | Opóźnienie |
|---|
| 1. ponowienie | 30 sekund |
| 2. ponowienie | 2 minuty |
| 3. ponowienie | 10 minut |
Zalecenia bezpieczeństwa
Wdróż idempotentność
Webhooki mogą być dostarczone więcej niż raz. Użyj taskId do deduplikacji i uniknięcia przetwarzania tego samego wyniku dwukrotnie.
const processedTasks = new Set();
app.post('/webhook/apixo', (req, res) => {
const { taskId } = req.body.data;
if (processedTasks.has(taskId)) {
return res.status(200).send('Already processed');
}
processedTasks.add(taskId);
// Process the task...
res.status(200).send('OK');
});
Używaj wyłącznie HTTPS
Zawsze używaj HTTPS dla endpointu webhooka, aby zapewnić szyfrowanie danych w tranzycie.
Testowanie webhooków
Użyj ngrok do udostępnienia lokalnego serwera podczas rozwoju:
ngrok http 3000
# Zwraca: https://abc123.ngrok.io — użyj tego jako callback_url
Nadal możesz sprawdzać status zadania przez API nawet w trybie callback — jest to przydatne przy debugowaniu.