> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Production Best Practices for the APIXO API

> Optimize your APIXO integration for production: retries, timeouts, webhook reliability, cost control, and error handling patterns.

Follow these recommendations to build robust, efficient integrations.

## Choosing Request Mode

| Mode | Best For | Pros | Cons |
| - | - | - | - |
| **Async (Polling)** | Client apps, simple scripts | Easy to implement | Requires polling logic |
| **Callback (Webhooks)** | Production servers | Real-time, no polling | Requires public endpoint |

<Info>
  Start with `async` mode for development, switch to `callback` for production.
</Info>

## Polling Strategy

For `async` mode, implement smart polling to balance responsiveness and efficiency.

### Recommended Intervals

| Model Type | Initial Wait | Poll Interval | Max Wait |
| - | - | - | - |
| Image (fast) | 5s | 3s | 2 min |
| Image (quality) | 10s | 5s | 3 min |
| Video | 60s | 15s | 10 min |
| Audio | 30s | 10s | 5 min |

### Exponential Backoff

```javascript theme={null}
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');
}
```

## Error Handling

### Always Handle Failures

```javascript theme={null}
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;
  }
}
```

### Implement Retries

```javascript theme={null}
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.
    }
  }
}
```

## Prompt Engineering

### Image Generation Tips

| Do | Don't |
| - | - |
| Be specific: "A golden retriever puppy playing in autumn leaves" | Be vague: "A dog" |
| Include style: "watercolor painting, soft lighting" | Assume defaults |
| Specify composition: "close-up portrait, centered" | Leave composition to chance |
| Use positive descriptions | Use negatives like "no background" |

### Effective Prompt Structure

```
[Subject] + [Action/Pose] + [Environment] + [Style] + [Technical details]
```

**Example:**

```
A young woman reading a book in a cozy cafe, 
warm afternoon sunlight through windows, 
impressionist oil painting style, 
soft focus background, golden hour lighting
```

## Resource Management

### Download Results Promptly

```javascript theme={null}
// 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
}
```

### Store Task IDs

```javascript theme={null}
// 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(),
});
```

## Cost Optimization

### Choose the Right Model

| Use Case | Recommended Model | Notes |
| - | - | - |
| Prototyping | Nano Banana | Fast iteration for quick feedback |
| Production quality | Flux-2 Pro | Balanced fidelity and control |
| Premium quality | Midjourney | Strong artistic style |
| Video (short) | Wan 2.5 | Efficient short-form generation |
| Video (cinematic) | Sora 2 | Highest-end video quality |

<Info>
  For current pricing, always refer to the <a href="https://apixo.ai/pricing">Pricing</a> page.
</Info>

### Batch Similar Requests

If generating multiple variations, use image-to-image mode instead of generating from scratch each time.

### Monitor Usage

```javascript theme={null}
// 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');
}
```

## Security

### Protect Your API Key

```javascript theme={null}
// 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
```

### Validate User Input

```javascript theme={null}
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();
}
```

## Performance

### Use Connection Pooling

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

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

### Parallelize When Possible

```javascript theme={null}
// 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))
);
```

## Monitoring

### Log API Calls

```javascript theme={null}
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,
  });
}
```

### Set Up Alerts

Monitor for:

* High error rates
* Unusual latency
* Cost spikes
* Rate limit hits


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.