이 페이지
Seedream API for Seedream 5.0 Pro
Seedream API에서 Seedream 5.0 Pro를 사용해 텍스트 또는 최대 10장의 공개 HTTPS 참조 이미지로 이미지 한 장을 생성합니다. Imya가 인증, 비동기 작업, 실시간 크레딧, 안전한 오류와 저장 결과를 관리합니다.
REST API · v1 · 비동기 작업
구축할 수 있는 기능
프롬프트 생성, 참조 기반 변형과 자동 이미지 생성을 하나의 REST 흐름으로 구현하세요.
제품·캠페인 이미지
텍스트로 제품 장면, 광고 콘셉트와 브랜드 비주얼을 생성합니다.
참조 기반 변형
1~10장의 참조 이미지로 피사체, 구도와 시각 방향을 안내합니다.
자동 이미지 워크플로
비동기로 제출하고 공개 task ID를 조회해 저장된 결과를 받습니다.
첫 Seedream API 요청 보내기
작업을 만들고 공개 task ID를 저장한 뒤 성공하거나 실패할 때까지 조회합니다.
- 1
API Key 생성
Imya 계정 설정에서 키를 발급합니다.
- 2
입력 선택
프롬프트만 사용하거나 참조 이미지 1~10장을 추가합니다.
- 3
결과 조회
공개 task ID를 5초 이상 간격으로 조회합니다.
인증과 멱등성
Imya API Key를 Bearer 토큰으로 보내고 생성 POST마다 고유한 Idempotency-Key를 사용해 네트워크 재시도의 중복 작업과 과금을 막습니다.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY이미지 생성 작업 만들기
텍스트 생성은 image_urls를 생략합니다. 참조 생성은 공개 HTTPS 이미지 1~10장을 추가합니다. 서버가 요청의 실시간 credits_reserved를 반환합니다.
/v1/images/generationscurl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-product-shot-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "A premium skincare bottle on pale stone, soft morning light",
"aspect_ratio": "4:3",
"quality": "basic",
"output_format": "png",
"n": 1
}'curl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-edit-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "Keep the product shape and place it in a warm studio",
"image_urls": ["https://cdn.example.com/input/product.png"],
"aspect_ratio": "4:3",
"quality": "high",
"output_format": "jpeg",
"n": 1
}'작업 조회
최신 상태, 최종 크레딧, 저장된 이미지 또는 안전한 오류를 반환합니다. 5초 이상 간격으로 조회하세요.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"요청 파라미터
| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| model | string | 예 | seedream-5-pro를 사용합니다. |
| prompt | string | 예 | 3~3,000자의 생성 지시입니다. |
| image_urls | string[] | 아니요 | 공개 HTTPS 참조 이미지 1~10장. 텍스트 생성은 생략합니다. |
| aspect_ratio | string | 아니요 | 1:1, 4:3, 3:4, 16:9, 9:16, 2:3 또는 3:2. 기본값 1:1. |
| quality | string | 아니요 | basic 또는 high. 16:9와 9:16은 basic만 지원합니다. |
| output_format | string | 아니요 | png 또는 jpeg. 기본값 png. |
| n | number | 아니요 | 반드시 1이며 이미지 한 장만 생성합니다. |
응답
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 44
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:38.000Z",
"credits_reserved": 44,
"credits_used": 44,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png"
}
]
}새 작업은 HTTP 202를 반환합니다. 동일한 멱등 재시도는 HTTP 200과 Idempotent-Replayed: true를 반환합니다. 성공 이미지는 succeeded 전에 Imya 저장소로 복사됩니다.
실시간 크레딧 과금
basic과 high의 기본 비용은 35크레딧입니다. 서버가 플랜 계수를 적용하고 credits_reserved를 반환합니다. 작업이 30분 안에 완료되지 않으면 실패 처리하고 대상 크레딧을 원래 만료일 그대로 한 번만 환불합니다.
크레딧 플랜 보기작업 상태
pending작업이 접수되어 시작을 기다립니다.
processing모델이 이미지를 생성 중입니다.
succeeded생성이 끝났고 data에 저장 이미지가 있습니다.
failed생성에 실패했습니다. 안전한 error 객체를 확인하세요.
오류
400Idempotency-Key가 없거나 JSON이 잘못되었습니다.
401API Key가 없거나 유효하지 않습니다.
402크레딧이 부족합니다.
403API 계정이 비활성화되었거나 요청이 허용되지 않습니다.
404작업이 없거나 이 계정 소유가 아닙니다.
409멱등 키를 다른 본문에 재사용했습니다.
413요청 본문이 64 KiB를 초과합니다.
415Content-Type은 application/json이어야 합니다.
422모델 파라미터, 프롬프트 또는 참조 이미지가 유효하지 않습니다.
429속도 또는 동시 실행 한도에 도달했습니다.
5xx요청을 완료하지 못했습니다. 새 요청 전에 원래 작업을 확인하세요.
Imya 공개 API 공통 계약
다음 규칙은 모든 공개 이미지·동영상 생성 엔드포인트에 적용됩니다. 모델별 필드와 요금은 위 파라미터 표를 따릅니다.
과금과 안전한 재시도
새 작업이 접수될 때 credits_reserved의 정확한 크레딧을 원자적으로 차감합니다. 같은 Idempotency-Key와 본문을 재전송하면 중복 과금 없이 원래 작업을 반환합니다.
시간 초과와 환불
30분 안에 종료되지 않은 작업은 실패합니다. 대상 크레딧은 원래 만료일을 유지하며 한 번만 환불됩니다.
속도와 동시 실행 제한
API Key당 60초에 120회 요청, 계정당 이미지 5개 또는 동영상 3개의 동시 작업 한도를 적용합니다. 429의 Retry-After를 따르세요.
조회와 소유권
생성 응답의 id로 GET /v1/tasks/{id}를 5초 이상 간격으로 조회합니다. 생성한 계정만 작업을 읽을 수 있으며 webhook, SDK, batch 제출은 제공하지 않습니다.
오류와 콘텐츠 안전
공개 오류는 업스트림 자격 증명, 내부 URL과 인프라 정보를 제거합니다. 안전하지 않은 프롬프트는 prompt_blocked로 거부될 수 있습니다.
이미지 결과 보관
무료 계정은 7일, 활성 유료 또는 Lifetime 계정은 최대 30일 보관합니다. 삭제 후 status는 failed이고 error.code는 media_deleted입니다.
Seedream API 프로덕션 연동 가이드
Seedream 5.0 Pro 연동을 긴 HTTP 요청이 아니라 복구 가능한 비동기 작업 시스템으로 설계하세요. Imya가 반환한 id를 저장하고 재시도를 결정적으로 처리합니다.
모델 계약에서 파라미터 선택
제출 전에 이 페이지의 파라미터 표로 요청을 검증하세요. 최소 지원 설정부터 시작하고 제품에 필요할 때만 품질, 크기, 길이 또는 참조 수를 늘립니다.
참조 순서를 보존하고 사용자가 모든 이미지에 대한 권리를 보유했는지 확인하세요.
복구 가능한 비동기 흐름 설계
이미지 작업을 제출하고 id를 저장한 뒤 백그라운드 워커에서 GET /v1/tasks/{id}를 5초 이상 간격으로 조회합니다. 공개 status는 pending, processing, succeeded, failed이며 30분의 하드 마감에 도달하면 중지합니다. webhook, SDK, batch 제출은 현재 제공하지 않습니다.
- 01UI 업데이트 전에 id, status, credits_reserved와 요청 식별자를 저장합니다.
- 02일시적 오류에는 백오프하고 429의 Retry-After를 준수하며 전송 오류를 새 유료 작업으로 자동 변환하지 않습니다.
- 03계정당 동시에 최대 5개의 이미지 작업과 API Key당 60초에 120회 요청을 허용합니다.
과금과 재시도를 결정적으로 처리
새 작업 접수 시 credits_reserved가 원자적으로 차감됩니다. 의도한 생성마다 Idempotency-Key를 저장하고 같은 본문으로 재사용하면 중복 과금 없이 원래 작업이 반환됩니다.
대상 실패 작업은 원래 만료일을 유지해 한 번만 환불됩니다. 처리 중에는 error.code가 refund_pending이고 완료 후 credits_refunded가 표시됩니다.
자격 증명, 소유권과 미디어 보호
API Key를 서버에 보관하고 id를 인증된 사용자 또는 워크스페이스에 연결하세요. 지원용 요청·작업 ID만 기록하고 프롬프트, 비공개 URL과 자격 증명을 노출하지 마세요.
이미지는 무료 계정 7일, 활성 유료 또는 Lifetime 계정 최대 30일 사용할 수 있습니다. 삭제 후 status는 failed이고 error.code는 media_deleted입니다.
프로덕션 체크리스트
- 제출 전에 모델별 필드를 검증합니다.
- 작업마다 Idempotency-Key와 본문을 저장합니다.
- 상태를 저장하고 5초 이상 간격으로 조회합니다.
- 계정 동시 실행과 Key 속도 제한을 적용합니다.
- 네 status와 media_deleted, refund_pending, credits_refunded를 처리합니다.
- 자격 증명을 서버에 두고 보관 정책을 정의합니다.
자주 묻는 질문
얼마나 자주 조회해야 하나요?
최소 5초를 기다리고 처리 중에는 더 느린 백오프를 사용하세요.
크레딧은 언제 차감되나요?
새 작업 접수 시 정확한 credits_reserved가 원자적으로 차감됩니다.
재시도가 중복 과금되나요?
같은 Idempotency-Key와 본문이면 원래 작업을 반환합니다.
최종 실패는 어떻게 처리하나요?
안전한 오류를 표시하고 id를 보관하며 credits_refunded로 서버 환불 완료를 확인하세요.
구축을 시작할까요?
첫 요청을 위한 API Key를 만들거나 온라인 생성기에서 프롬프트, 참조와 품질을 시험하세요.