기능별
이미지
모델을 고르고, 요청을 복사하고, 이미지를 받으세요. 아래 내용은 모두 선택한 모델에 맞춰 바뀝니다.
#1. 모델 선택
doubao-seedream-5-0-pro$0.02928 / 요청비동기 작업제한 및 상태
이 용도로 사용할 수 있는 온라인 모델이 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": "Seedream 5.0 Pro",
"prompt": "A cinematic scene with careful composition",
"size": "auto",
"resolution": "1K",
"n": 1,
"output_format": "jpeg",
"watermark": false,
"optimize_prompt_options": {
"mode": "standard"
}
}')
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이 요청에 사용할 정확한 모델 식별자.
doubao-seedream-5-0-propromptGeneration/editing instruction. Optional only when layer_decomposition is true. Point and box tags use normalized 0..1000 coordinates.
imagesOptional reference image URLs or data URIs, up to 10. Layer decomposition and transparent editing require exactly one image.
sizeauto, 1K, 1.5K, 2K, a supported aspect ratio, or an exact WIDTHxHEIGHT value. Exact pixels must total 921600..4624220.
resolution요청할 출력 해상도.
1K1.5K2Kn1응답 흐름
작업 상태, 최종 상태, 결과 응답 예시.
응답 흐름
작업 상태, 최종 상태, 결과 응답 예시.
{
"id": "task_xxx",
"task_id": "task_xxx",
"object": "image.task",
"model": "Seedream 5.0 Pro",
"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나 오류 메시지를 보내 주시면 확인해 드리겠습니다.