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

# 개발 가이드

> 애플리케이션에 API 통합하기

# 개발 가이드

이 가이드는 API 서비스를 애플리케이션에 통합하는 데 도움을 드립니다.

## 비동기 처리

API는 비동기 처리 모델을 사용합니다:

1. 작업 제출: 생성 요청을 보내고 작업 ID를 받습니다
2. 상태 폴링: 주기적으로 작업 상태를 확인합니다
3. 결과 가져오기: 작업이 완료되면 생성 결과를 가져옵니다

### 폴링 예제

```python theme={null}
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")
```

## 오류 처리

### 일반적인 오류

| 상태 코드 | 설명          | 해결 방법           |
| ----- | ----------- | --------------- |
| 400   | 잘못된 요청 매개변수 | 요청 매개변수 및 형식 확인 |
| 401   | 인증 실패       | API 키 확인        |
| 402   | 잔액 부족       | 계정 잔액 충전        |
| 429   | 요청 제한 초과    | 요청 빈도 감소        |
| 500   | 서버 오류       | 나중에 재시도         |

### 예제

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

## 모범 사례

1. 캐싱: 생성된 이미지/비디오 링크는 24시간 동안 유효합니다
2. 재시도: 일시적인 오류에 대해 지수 백오프를 구현하세요
3. 모니터링: 정기적으로 API 사용량 및 할당량을 확인하세요
4. 보안: API 키를 안전하게 보관하세요

## 지원

개발 중 문제가 발생하면 다음을 통해 도움을 받을 수 있습니다:

* 이메일: [zhihong@apimart.ai](mailto:zhihong@apimart.ai)
* 실시간 채팅: 웹사이트 방문
* 문서: 전체 API 문서 탐색