기능별
이미지
모델을 고르고, 요청을 복사하고, 이미지를 받으세요. 아래 내용은 모두 선택한 모델에 맞춰 바뀝니다.
#1. 모델 선택
gpt-image-2.5-sunburst입력 $4.80 · 출력 $28.80 / 1M비동기 작업제한 및 상태
이 용도로 사용할 수 있는 온라인 모델이 12개 있습니다. 모델을 바꾸면 아래 코드도 바뀝니다.
#2. 요청 복사
YOUR_API_KEY를 내 키로 바꾼 뒤 실행하세요. 표시된 옵션은 이 모델이 받는 옵션입니다.
https://www.aisplice.store/v1/images/tasksBearer API key비동기 작업옵션이 모델에 공개된 옵션만 표시됩니다.
# Requires curl and jq
API_KEY="${API_KEY:-YOUR_API_KEY}"
# 1. Submit once
SUBMITTED=$(curl --fail-with-body -sS https://www.aisplice.store/v1/images/tasks \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: model-docs-$(date +%s)-$$" \\
-d '{
"model": "GPT Image 2.5 Sunburst",
"prompt": "A cinematic scene with careful composition",
"size": "auto",
"resolution": "1K",
"n": 1,
"quality": "auto",
"background": "auto",
"moderation": "low",
"output_format": "png"
}')
TASK_ID=$(printf '%s' "$SUBMITTED" | jq -r '.task_id // .id // empty')
if [ -z "$TASK_ID" ]; then
printf '%s\n' "$SUBMITTED" >&2
exit 1
fi
echo "task_id=$TASK_ID"
# 2. Poll until terminal
while true; do
STATUS_JSON=$(curl --fail-with-body -sS \
"https://www.aisplice.store/v1/images/tasks/$TASK_ID" \
-H "Authorization: Bearer $API_KEY")
STATUS=$(printf '%s' "$STATUS_JSON" | jq -r '.status // empty' | tr '[:upper:]' '[:lower:]')
echo "status=$STATUS"
case "$STATUS" in
completed|succeeded|success) break ;;
failed|failure|cancelled|canceled)
printf '%s\n' "$STATUS_JSON" | jq .
exit 1
;;
esac
sleep 3
done
# 3. Fetch the final result
curl --fail-with-body -sS \
"https://www.aisplice.store/v1/images/tasks/$TASK_ID/content" \
-H "Authorization: Bearer $API_KEY" | jq .이 모델에는 공개 미디어 URL이 필요합니다. 먼저 로컬 파일을 업로드한 뒤 모델 요청에 public_url을 넣으세요. 큰 Base64 본문은 피하세요.
업로드 가이드 읽기모든 파라미터
이 모델이 받는 모든 필드와 허용 값.
모든 파라미터
이 모델이 받는 모든 필드와 허용 값.
model이 요청에 사용할 정확한 모델 식별자.
gpt-image-2.5-sunburstprompt원하는 결과를 설명하는 지시문.
sizeAspect ratio or exact pixels such as 1600x1200. Exact dimensions must be multiples of 16; sides <=3840, ratio <=3:1, area 655360-8294400.
resolution요청할 출력 해상도.
1K2K4Kn1234imagesReference images; data URLs are materialized before upstream submission.
quality요청할 출력 품질 등급.
autolowmediumhighxhighmax응답 흐름
작업 상태, 최종 상태, 결과 응답 예시.
응답 흐름
작업 상태, 최종 상태, 결과 응답 예시.
{
"id": "task_xxx",
"task_id": "task_xxx",
"object": "image.task",
"model": "GPT Image 2.5 Sunburst",
"status": "queued"
}{
"created": 1720000000,
"data": [
{
"url": "https://media.example/result.png"
}
]
}대기 중
queued · submitted · in_progress · processing
성공
completed · succeeded · success
실패
failed · failure · cancelled · canceled
#3. 결과 받기
제출 호출은 바로 task_id로 응답합니다. status가 completed가 될 때까지 몇 초마다 작업을 조회하거나, webhook_url을 넘기면 완료 시 저희가 호출해 드립니다.
GET https://www.aisplice.store/v1/images/tasks/{task_id}
GET https://www.aisplice.store/v1/images/tasks/{task_id}/content
성공했을 때만 과금
#문제가 생겼을 때
- 필드 이름과 함께 400: 이 모델이 받지 않는 옵션입니다. 2단계에 나열된 값을 사용하세요.
- 모델이 콘텐츠를 거부함: 프롬프트를 바꿔 쓰세요. 거부된 요청은 과금되지 않습니다.
- 402: 잔액이 이 요청에 부족합니다. 지갑에서 충전한 뒤 다시 시도하세요.
- 429: 요청 속도를 줄이고 Retry-After 초만큼 기다린 뒤 다시 시도하세요.
- 503 model_not_found: 모델 이름이 틀렸거나 모델이 오프라인입니다. 1단계에서 다시 고르세요.
#참조 이미지
2단계에 나열된 참조 이미지 필드에 공개 이미지 URL을 넣으세요. 로컬 파일은 먼저 업로드하고 반환된 URL을 사용하세요.
제품에 통합하기사용자에게 먼저 보여 줄 옵션과 나중에 추가할 옵션.
사용자에게 먼저 보여 줄 옵션프롬프트와 가격에 영향을 주는 옵션 하나로 시작하고, 기본 흐름이 동작하면 나머지를 추가하세요.+
창작 의도
prompt 같은 필드는 사용자가 무엇이 바뀌는지 바로 이해할 수 있으므로 UI에 두어야 합니다.
비용 배수 항목
duration, resolution, size, count 같은 필드는 가격을 명확히 설명할 수 있을 때만 도입하세요.
모드 전환 항목
image, mask, 후속 작업 ID 같은 필드는 워크플로 자체를 바꾸므로 전용 모드에서만 보여야 합니다.
시스템 연동 항목
webhook_secret 같은 필드는 일반 크리에이터가 아닌 연동 개발자를 위한 것이므로 기본 UI에서 빼 두세요.
prompt- 노출 시점
- 항상 노출합니다. 이미지 작업의 핵심 창작 입력입니다.
- 권장 기본값
- UI에서 필수.
- 중요한 이유
- 결과를 직접 결정하므로 숨기면 기능을 쓸 수 없습니다.
size- 노출 시점
- 출력 크기에 따라 과금이 달라진다면 첫 릴리스부터 노출합니다.
- 권장 기본값
- 1:1 같은 권장 화면 비율 하나로 시작합니다.
- 중요한 이유
- 비용과 출력 구도에 모두 영향을 주므로, 사용자에게 초기부터 간단한 크기 선택지가 필요합니다.
quality- 노출 시점
- 사용자가 더 높거나 저렴한 등급을 분명히 요청한 뒤에만 노출합니다.
- 권장 기본값
- 서버 측에서 모델 기본값으로 유지합니다.
- 중요한 이유
- 가격과 지연 시간을 바꾸지만 보통 처음부터 제공할 필요는 없습니다.
n- 노출 시점
- 일괄 생성이 핵심 워크플로일 때만 노출합니다.
- 권장 기본값
- 기본값은 1입니다.
- 중요한 이유
- 비용이 즉시 배로 늘고 첫 사용 경험이 복잡해질 수 있습니다.
mask / image- 노출 시점
- 편집 또는 참조 이미지 제품에서만 노출합니다.
- 권장 기본값
- 텍스트→이미지 모드에서는 숨깁니다.
- 중요한 이유
- 이 필드들은 제품을 생성에서 편집으로 바꾸므로 기본 흐름에 섞이면 안 됩니다.
Phase 1
- prompt
- one size or one duration default
- submit -> poll -> content
Phase 2
- one quality or resolution selector
- clear pricing hint
Phase 3
- advanced controls such as reference media, continuation, webhook, or vendor-specific tuning결과의 기준은 하나로 유지
아직 해결되지 않았나요?
요청 ID나 오류 메시지를 보내 주시면 확인해 드리겠습니다.