CloudRelay-이미지생성-스킬은(는) 무엇을 하나요?
CloudRelay의 비동기 이미지 API를 위한 크로스 클라이언트 에이전트 스킬로, Cloudflare의 약 120초 타임아웃을 우회하고 에이전트에게 작업 제출, 폴링, 결과 처리 방법을 가르쳐줍니다.
개요
이 스킬은 에이전트가 CloudRelay의 비동기 이미지 생성 API와 상호 작용할 수 있도록 합니다. Cloudflare Workers는 최대 120초의 실행 시간 제한이 있으므로, 긴 이미지 생성 작업은 비동기적으로 처리되어야 합니다. 이 스킬은 에이전트에게 다음 작업 흐름을 안내합니다:
- 작업 제출 (
POST /api/jobs) - 작업 상태 폴링 (
GET /api/jobs/:id) - 완료된 결과 수신 (
GET /api/jobs/:id/result)
필수 조건
- 유효한 CloudRelay API 키 (
CLOUDRELAY_API_KEY) cloudrelay.com기본 URL- HTTPie 또는 curl (CLI 예제용)
환경 변수
export CLOUDRELAY_API_KEY="your-api-key-here"
export CLOUDRELAY_BASE_URL="https://api.cloudrelay.com"
API 엔드포인트
1. 이미지 생성 작업 제출
# 이미지 생성 작업 제출
http POST "$CLOUDRELAY_BASE_URL/api/jobs" \
Authorization:"Bearer $CLOUDRELAY_API_KEY" \
prompt="An astronaut riding a horse on Mars" \
width=1024 \
height=1024 \
steps=50
요청 본문:
| 필드 | 타입 | 설명 | 기본값 |
|---|---|---|---|
prompt | 문자열 | 이미지 생성을 위한 프롬프트 | (필수) |
width | 정수 | 이미지 너비 | 512 |
height | 정수 | 이미지 높이 | 512 |
steps | 정수 | 샘플링 단계 수 | 30 |
성공 응답:
{
"id": "job_abc123",
"status": "queued",
"created_at": "2025-03-22T12:00:00Z"
}
2. 작업 상태 폴링
작업 ID로 상태를 폴링합니다:
# 작업 상태 확인
http GET "$CLOUDRELAY_BASE_URL/api/jobs/job_abc123" \
Authorization:"Bearer $CLOUDRELAY_API_KEY"
응답 상태:
| 상태 | 설명 |
|---|---|
queued | 작업이 대기열에 있음 |
processing | 이미지가 생성 중 |
completed | 이미지가 완료되어 검색 가능 |
failed | 작업이 실패함 (오류 메시지 포함) |
완료 예제 응답:
{
"id": "job_abc123",
"status": "completed",
"result_url": "https://cdn.cloudrelay.com/images/job_abc123.png",
"completed_at": "2025-03-22T12:05:00Z"
}
3. 결과 수신
완료 시 결과 URL에서 이미지를 가져옵니다:
# 생성된 이미지 다운로드
wget https://cdn.cloudrelay.com/images/job_abc123.png
또는 작업 ID에서 직접:
# 결과 엔드포인트에서 다운로드
http GET "$CLOUDRELAY_BASE_URL/api/jobs/job_abc123/result" \
Authorization:"Bearer $CLOUDRELAY_API_KEY" > output.png
에이전트 사용 예제
작업 제출 (Claude Code)
에이전트는 `CLOUDRELAY_API_KEY`가 설정되어 있는지 확인한 후, 다음 API 호출을 수행합니다:
1. `POST /api/jobs`를 적절한 페이로드로 호출하여 작업을 제출합니다.
2. 응답에서 `id` 필드를 추출합니다.
3. `status`가 `completed` 또는 `failed`가 될 때까지 5초마다 `GET /api/jobs/:id`를 폴링합니다.
4. `completed`인 경우 `result_url` 또는 `/api/jobs/:id/result`에서 이미지를 가져옵니다.
5. `failed`인 경우 오류 메시지를 사용자에게 보고합니다.
폴링 지연
Cloudflare 제한을 초과하지 않기 위해:
- 처음 90초 동안은 5초마다 폴링합니다.
- 90초 후에는 10초마다 폴링합니다.
- 최대 300초(5분) 동안 기다린 후 타임아웃됩니다.
일반적인 오류
| 오류 코드 | 설명 | 해결 방법 |
|---|---|---|
401 | 인증 실패 - API 키 누락 또는 잘못됨 | CLOUDRELAY_API_KEY 확인 |
429 | 속도 제한 초과 | 재시도 전에 잠시 기다림 |
500 | 서버 내부 오류 | CloudRelay 지원팀에 문의 |
보안 고려 사항
- API 키를 코드나 버전 관리에 절대 하드코딩하지 마십시오.
- 프로덕션 환경에서는 환경 변수나 비밀 관리자를 사용하십시오.
result_url은 일회용이며 만료될 수 있으므로, 에이전트는 가능한 빨리 다운로드해야 합니다.