Seedream 5.0 Pro 이미지 API 사용 방법

하나의 POST 요청, 하나의 API 키, 하나의 후속 단계로 Seedream 5.0 Pro를 작동시킬 수 있습니다: 작업을 제출하고 task_id를 받은 다음, 이미지가 완료될 때까지 상태를 확인하세요. 그 두 번째 단계를 놓치면 최종 파일을 얻지 못합니다.

짧은 버전은 다음과 같습니다:

• https://api.apimart.ai/v1/images/generations로 요청을 보냅니다
• Authorization: Bearer YOUR_API_KEY를 추가합니다
• model을 doubao-seedream-5-0-pro로 설정합니다
• prompt, size, n을 포함합니다
• 새로운 이미지 아이디어에는 **텍스트-투-이미지**를 사용합니다
• 출력이 하나 이상의 참조 이미지에 더 가깝게 유지되기를 원할 때는 이미지-투-이미지를 사용합니다
• 이미지 URL을 빠르게 저장합니다 — 24시간 후에 만료되기 때문입니다
• 3K 이미지처럼 약 35~50초가 걸릴 수 있는 느린 출력에는 비동기 작업을 사용합니다
• 가격이 이미지당 약 $0.0320이므로 비용을 주시합니다

제가 가장 기억할 것: 키를 서버에 두고, n을 숫자로 전달하며, 더 긴 작업에는 폴링이나 웹훅을 사용하세요.

몇 가지 세부 사항은 보이는 것보다 더 중요합니다. 예를 들어, 401은 종종 키가 없거나 Bearer 형식이 잘못되었음을 의미합니다. 403은 종종 키는 작동하지만 계정이 모델을 사용할 수 없거나 잔액이 부족함을 의미합니다. 그리고 Base64 출력을 사용한다면, 브라우저에 표시하기 전에 data:image/...;base64, 접두사를 직접 추가해야 합니다.

빠른 비교

요약: 이 가이드는 인증을 설정하고, 요청 본문을 구성하고, T2I와 I2I 중 선택하고, 비동기 작업을 처리하고, 파일을 잃거나 지출을 낭비하지 않고 결과를 저장하는 방법을 보여줍니다.

2. API 액세스 및 인증 설정

2.1 APIMart 계정 만들기 및 API 키 생성

APIMart 웹사이트로 가서 새 계정에 가입하세요 ^[8]. 그런 다음 대시보드에서 API 키 관리 페이지를 열고 API 키를 생성하세요 ^[1][5].

그 키를 즉시 복사해 서버 측에 저장하세요. 시크릿 매니저나 환경 변수가 가장 안전한 장소입니다.

API 키를 프론트엔드 코드나 공개 저장소에 절대 넣지 마세요. 누군가 그 키를 손에 넣으면 당신의 계정을 사용할 수 있습니다. Node.js에서는 process.env.API_KEY로 저장하세요. 셸 환경에서는 export API_KEY="your-key-here"를 사용하세요 ^[1][6].

전체 요청 플로우를 구축하기 전에, 작은 POST 요청을 보내 액세스가 작동하는지 확인하세요 ^[1][2]. 200 OK 응답을 받으면 키와 권한이 올바르게 설정된 것입니다.

그 후 모델과 프롬프트를 포함한 요청 필드로 넘어갈 수 있습니다.

2.2 베이스 URL 및 Bearer 인증 헤더 설정

T2I 또는 I2I 모드를 골랐고 키가 준비되면, 이미지 요청이 작동하기 전에 인증을 설정해야 합니다. 모든 요청과 함께 이 헤더들을 보내세요:

Bearer 접두사가 중요합니다. 빼먹으면 요청이 실패합니다 ^[2][5]. 또한 Bearer 뒤에 정확히 하나의 공백을 사용하세요.

HTTP 상태 코드는 인증 문제를 빠르게 발견하는 데 도움이 됩니다 ^[1][10]. 401 Unauthorized 오류는 보통 키가 없거나 유효하지 않거나 Bearer 접두사가 포함되지 않았음을 의미합니다 ^[1][10]. 403 Forbidden 오류는 보통 키 자체는 유효하지만 계정에 모델 액세스나 충분한 잔액이 없음을 의미합니다 ^[1][10].

이를 검증하는 좋은 방법은 먼저 cURL로 테스트하는 것입니다. cURL은 작동하는데 앱이 작동하지 않는다면, 버그는 아마도 앱의 요청 코드에 있습니다 ^[2][6].

인증이 설정되면, 다음 단계는 이미지 요청 본문을 구성하는 것입니다.

3. Seedream 5.0 Pro 이미지 요청 구성

3.1 필수 필드: 모델, 프롬프트, 크기, 이미지 개수

인증이 설정되면, 다음 단계는 JSON 본문을 구성하는 것입니다.

유효한 요청 본문에는 네 개의 필드가 필요합니다: model, prompt, size, n.

Seedream 5.0 Pro의 경우 model을 doubao-seedream-5-0-pro로 설정하세요 ^[1]. prompt 필드는 자연어 설명을 받으며 최대 5,000자를 지원합니다 ^[2]. size 필드는 출력 치수나 종횡비를 제어합니다. 일반적인 값에는 1024x1024, 2K, 그리고 1:1이나 16:9 같은 종횡비가 포함됩니다 ^[1][2]. n 필드는 생성할 이미지 수를 설정하며, 보통 1에서 15까지입니다 ^[1][6].

작은 세부 사항 하나가 사람들의 발목을 잡을 수 있습니다: n은 문자열이 아니라 정수여야 합니다. 1 대신 "1"을 전달하면 API는 검증 오류를 반환합니다 ^[1][5].

3.2 선택 필드: 참조 이미지, 웹 검색, 비동기 작업

image_urls는 이미지-투-이미지 모드의 주요 필드입니다. 이를 사용해 최대 14개의 참조 이미지를 URL이나 Base64 데이터 URI로 보내세요. 각 이미지는 10 MB 미만이어야 하며 1:3과 3:1 사이의 종횡비를 사용해야 합니다 ^[1]. Base64를 사용한다면, 전체 데이터 URI 접두사 — data:image/jpeg;base64, — 를 포함하세요. 그렇지 않으면 요청이 실패합니다 ^[1][5].

web_search는 시사나 브랜드 로고 같은 사실적이거나 실시간 프롬프트에 도움이 될 수 있습니다 ^[4][7]. 대부분의 표준 이미지 생성에서는 필요하지 않습니다.

비동기 또는 배치 작업의 경우, callback_url은 APIMart가 작업 완료 페이로드를 POST할 공개 HTTPS 엔드포인트를 받습니다 ^[2].

3.3 cURL 및 JavaScript 샘플 API 호출

다음은 단일 1024×1024 이미지를 위한 최소 작동 cURL 요청입니다:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "size": "1024x1024",
    "n": 1
  }'

그리고 다음은 fetch를 사용한 Node.js에서의 동일한 요청입니다:

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro",
    prompt: "A sunlit mountain trail in autumn, photorealistic, wide angle",
    size: "1024x1024",
    n: 1
  })
});

const data = await response.json();
console.log(data);

이 요청을 서버 측에 유지하세요. 클라이언트 측 코드에 API 키를 절대 노출하지 마세요.

요청을 제출하면, 다음 단계는 응답 페이로드를 파싱하는 것입니다.

4. 응답 처리 및 일반적인 이미지 워크플로 실행

4.1 이미지 URL, Base64 출력, 오류 객체 파싱

요청이 완료되면, 하나의 이미지를 보냈든 여러 개를 보냈든 응답 형태는 동일하게 유지됩니다.

성공적인 응답은 네 개의 최상위 필드를 가진 JSON 객체를 반환합니다: model, created(Unix 타임스탬프), data(이미지 객체 배열), usage ^[6]. 생성된 각 이미지는 요청한 형식에 따라 data 안에 url 또는 b64_json 문자열로 나타납니다. n이 1보다 크면, data에는 출력당 하나의 이미지 객체가 포함됩니다.

URL 형식을 사용했다면, data의 각 항목은 이미지 링크를 .url에 저장합니다. 그 값을 브라우저에서 이미지 src로 설정할 수 있습니다. 한 가지 주의점: 이것들은 임시 서명 링크이며 24시간 후에 만료됩니다 ^[6]. 프로덕션 앱의 경우, URL을 저장하는 대신 파일을 즉시 다운로드해 영구 스토리지에 저장하세요.

Base64 형식을 사용했다면, data의 각 항목은 원시 문자열을 .b64_json에 저장합니다. 여기에는 data:image/...;base64, 접두사가 포함되지 않습니다 ^[6]. 브라우저에 표시하려면 그 접두사를 직접 추가하세요:

img.src = "data:image/png;base64", + data.b64_json;

Python에서 파일로 저장하려면, 먼저 디코딩하세요:

import base64

image_data = base64.b64decode(response["data"][0]["b64_json"])
with open("output.png", "wb") as f:
    f.write(image_data)

요청이 실패하면, 응답에는 code와 message 필드가 포함됩니다 ^[6]. 400은 보통 지원되지 않는 크기나 잘못된 파라미터를 의미합니다. 401은 요청이 인증되지 않았음을 의미합니다. 매번 두 필드를 모두 로깅하세요. 대부분의 경우 message가 문제를 곧바로 가리킵니다.

이 필드들을 사용해 출력을 저장할지, 디코딩할지, 표시할지 결정하세요.

---

4.2 Seedream 5.0 Pro로 생성할 수 있는 세 가지 일반적인 이미지 유형

이 세 가지 패턴은 앞서 다룬 모드와 일치합니다: 텍스트 전용, 단일 참조, 다중 참조.

• 텍스트 전용 마케팅 비주얼. 더 많은 디테일이 필요한 캠페인 에셋의 경우, 3K 해상도(size: "3K")를 사용하고 피사체와 장면 레이아웃으로 시작한 다음 조명, 스타일, 색상 디테일을 추가하는 구조화된 prompt를 작성하세요. 3K 생성은 35~50초가 걸리므로 보통 비동기가 더 나은 선택입니다.

• 단일 참조 제품 변형. image_urls에 하나의 참조 이미지를 넣고 배경, 조명, 표면 질감처럼 원하는 것만 변경하는 집중된 prompt로 이미지-투-이미지 모드를 사용하세요. 이는 처음부터 생성하는 것보다 제품의 형태와 디테일을 소스 이미지에 더 가깝게 유지합니다. 3K 변형의 경우, 각 작업이 약 40초 걸릴 수 있으므로 callback_url을 사용하세요 ^[2].

• 브랜드 및 캐릭터 일관성을 위한 다중 참조 일관성. 캐릭터나 브랜드 요소를 여러 이미지에 걸쳐 일관되게 유지해야 한다면, image_urls를 통해 최대 14개의 참조 이미지를 전달하세요 ^[2][3]. 참조 입력에서 여러 출력을 만들 때 sequential_image_generation을 auto로 설정하면 시각적 일관성을 잃지 않으면서 다양성을 유지할 수 있습니다 ^[5][4]. 이는 소셜 콘텐츠 시리즈, 제품 카탈로그, 캐릭터 시트에 잘 작동합니다.

이 패턴들은 응답 형식이 워크플로에 맞을 때 가장 잘 작동하는 경향이 있습니다.

---

4.3 동기 vs. 비동기 요청 및 URL vs. Base64 응답

통합을 출시하기 전에 응답 형식을 고르려면 이 비교를 사용하세요.

비동기 작업의 경우, 첫 폴링 전에 약 20초 기다린 다음 3초마다 확인하세요 ^[2]. 프로덕션에서는 callback_url이 폴링 루프를 피하고 서버 오버헤드를 줄이기 때문에 더 나은 옵션입니다 ^[2][9].

기본적으로 URL 응답을 사용하세요. 동일한 응답에 이미지 데이터가 필요할 때만 Base64로 전환하세요.

5. 안정적인 Seedream 5.0 Pro 통합을 위한 최종 체크리스트

첫 번째 성공적인 테스트 호출 후, 프로덕션으로 확장하기 전에 이 체크리스트를 훑어보세요. 출시를 꽁꽁 멈추게 하는 문제들을 잡는 간단한 방법입니다.

인증 및 키 보안. API 키를 환경 변수나 시크릿 매니저에 보관하세요. 백엔드에서 Authorization: Bearer <your_key>로 요청을 보내세요.

보내기 전에 요청 파라미터를 검증하세요. 모델 문자열을 확인하고, n을 정수로 전달하고, image_urls를 허용된 한도 내로 유지하며, 요청한 size가 지원되는지 확인하세요.

빠른 미리보기보다 오래 걸리는 작업의 경우, 전달 경로를 그에 맞게 조정하세요. 출력 크기에 따라 타임아웃을 설정하고, 장시간 실행 작업에는 폴링 대신 callback_url을 사용하세요.

이미지가 준비되면, 전달을 단순한 응답 문제가 아니라 스토리지 문제로 취급하세요. URL 출력을 사용한다면, 파일을 즉시 다운로드해 영구 스토리지로 옮기세요. 서명 URL은 24시간 후에 만료됩니다 ^[6].

확장하기 전에 작은 배치에서 프롬프트를 테스트하세요. Seedream 5.0은 생성된 이미지당 약 $0.0320으로 청구됩니다 ^[2]. 지연 시간과 지출을 주시할 수 있도록 createTime, completeTime, costTime을 로깅하세요 ^[2].

자주 묻는 질문

::: faq

task_id를 받은 후 비동기 이미지 작업을 어떻게 확인하나요?

반환된 task_id를 사용해 비동기 이미지 작업의 상태를 확인하세요.

API가 제공하는 상태 엔드포인트로 GET 요청을 보내세요. 많은 API에서 이는 다음과 같은 형태입니다:

• /v1/tasks/{task_id}
• 또는 task_id가 포함된 쿼리 스타일 엔드포인트

프로덕션 사용의 경우, 작업을 생성한 후 첫 상태 확인 전에 약 20초 기다리세요. 그 후 작업 상태가 completed로 표시될 때까지 3초마다 폴링하세요.

작업이 완료되면, 응답 페이로드를 읽고 거기서 이미지 URL을 가져오세요. :::

::: faq

Base64 대신 URL 출력을 언제 사용해야 하나요?

대부분의 경우 URL 출력을 사용하세요. 생성된 이미지로의 직접 링크를 제공하여 웹이나 모바일 앱에 연결하기 더 쉽게 만듭니다.

메모리 기반 처리나 두 번째 요청을 건너뛰고 싶을 때처럼 설정이 응답 본문 안에 이미지 데이터를 인라인으로 필요로 할 때만 Base64를 사용하세요. 고해상도 4K 에셋의 경우 URL 출력이 보통 더 효율적입니다. :::

::: faq

생성된 이미지를 잃지 않는 가장 좋은 방법은 무엇인가요?

생성된 이미지를 즉시 저장하세요. API 이미지 링크는 72시간 동안만 유효하기 때문입니다.

Seedream 5.0 Pro API는 비동기로 실행됩니다. 즉, 이미지 URL을 바로 받지 못합니다. 먼저 태스크 ID를 받습니다. 그런 다음 그 태스크 ID를 사용해 이미지 URL을 가져옵니다.

출력을 잃지 않으려면 두 가지 주요 옵션이 있습니다:

• 이미지가 준비될 때까지 태스크 ID로 폴링
• 콜백 URL을 사용해 시스템이 링크가 만료되기 전에 이미지를 받고 캡처하고 저장

너무 오래 기다리면 URL이 만료되고 이미지가 손실될 수 있습니다. :::