Skip to main content

Development Guide

This guide helps you integrate our API services into your application.

Asynchronous Processing

Our API uses an asynchronous processing model:
  1. Submit a task: send a generation request and receive a task ID
  2. Poll status: periodically check task status
  3. Get results: fetch generation results when the task completes

Polling example

import time
import requests

def wait_for_completion(api_key, task_id, max_wait=300):
    """Poll the task until it completes"""
    url = f"https://api.apimart.ai/v1/tasks/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    start_time = time.time()

    while time.time() - start_time < max_wait:
        data = requests.get(url, headers=headers).json()["data"]
        status = data["status"]

        if status == "completed":
            return data["result"]
        elif status in ("failed", "cancelled"):
            raise Exception(f"Task {status}: {data.get('error')}")

        time.sleep(2)  # wait 2 seconds before polling again

    raise Exception("Task timeout")

Error Handling

Common errors

StatusDescriptionResolution
400Invalid request parametersCheck request parameters and format
401Authentication failedVerify your API key
402Insufficient balanceTop up your account balance
429Rate limit exceededReduce request frequency
500Server errorRetry later

Example

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"model": "gpt-4o-image", "prompt": "a cute panda"},
)

if response.status_code != 200:
    error = response.json().get("error", {})
    if response.status_code == 401:
        print("Invalid API key")
    elif response.status_code == 402:
        print("Insufficient account balance")
    else:
        print(f"Error: {error.get('message')}")

Best Practices

  1. Caching: generated image/video links are valid for 24 hours
  2. Retries: implement exponential backoff on transient errors
  3. Monitoring: regularly check API usage and quotas
  4. Security: keep your API key secure

Support

If you run into issues during development, you can get help via:
  • Email: zhihong@apimart.ai
  • Live chat: visit our website
  • Docs: browse the full API documentation