> ## 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.

# Best Practices

> Optimize your APIXO integration for performance and reliability

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