탐색으로 건너뛰기
BeatAPIQwen Image 2 1Image API

Qwen Image 2.1

텍스트와 최대 10장의 참조 이미지로 1K 또는 2K 이미지를 생성하거나 편집하며, 투명 PNG나 WebP로도 받을 수 있습니다.

  • 비동기 방식입니다. 생성 요청은 곧바로 작업 ID를 반환하며, 작업이 성공하면 이미지가 도착합니다.
  • 작업 하나에 이미지 한 장입니다. 여러 장이 필요하면 작업을 여러 개 만드세요.
  • 텍스트로 이미지를 만들거나, 공개 HTTPS 링크로 전달한 최대 10장의 참조 이미지를 편집·합성합니다.
  • background: "transparent"와 output_format png 또는 webp로 투명 배경을 만듭니다. JPEG은 투명도를 담을 수 없습니다.
  • 프롬프트 재작성(enhance_prompt)은 따로 지정하지 않으면 텍스트로 이미지 생성에서는 켜지고 편집에서는 꺼집니다.
  • resolution(1K 또는 2K)에 따라 이미지당 가격이 정해집니다. 실패한 작업은 비용이 들지 않습니다.
POST/v1/images/tasks실행해 보기

API Explorer에서 이 모델을 엽니다. BeatAPI API 키를 입력해 작업을 만드세요. 실제 호출이며 본인 잔액에서 과금됩니다.

엔드포인트와 인증

POST https://api.beatapi.io/v1/images/tasks

Authorization string 필수

BeatAPI API 키를 Bearer <BEATAPI_API_KEY>로 보내세요. 키는 대시보드에서 만듭니다. 키는 서버에 보관하고, 브라우저나 모바일 앱에 포함하지 마세요.

본문은 Content-Type: application/json과 함께 JSON으로 보냅니다. Idempotency-Key는 선택 사항입니다. 논리적 요청마다 고유한 값(최대 255자)을 보내고, 완전히 같은 본문을 재시도할 때만 다시 사용하세요. 24시간 안에 같은 키와 본문으로 재시도하면 첫 응답을 Idempotent-Replayed: true와 함께 다시 반환하고, 같은 키에 다른 본문을 보내면 409 idempotency_conflict를 반환합니다. 2xx 이외의 응답은 저장되지 않으므로 400이나 402 이후의 재시도는 다시 실행됩니다.

요청 처리 방식

1

작업 만들기

아래 파라미터를 엔드포인트로 POST하세요. 201은 작업이 접수되었고 가격만큼 잔액이 보류되었다는 뜻이며, 작업은 백그라운드에서 실행됩니다. data.id를 저장하세요.

2

완료 기다리기

status가 succeeded 또는 failed가 될 때까지 GET /v1/tasks/{task_id}를 호출하고, 호출 사이에 data.poll_after_seconds만큼 기다리세요(이미지 5초, 영상 8초). 또는 task.succeeded와 task.failed에 대한 웹훅을 등록하세요. 처리 시간 초과로 중단된 작업은 이벤트를 보내지 않으므로 폴링은 대비책으로 유지하세요.

3

결과 저장하기

succeeded이면 모든 data.output.media[].url을 다운로드해 필요한 파일을 저장하세요. BeatAPI는 결과 URL을 얼마 동안 사용할 수 있는지 보장하지 않습니다. failed이면 data.error_code와 data.error_message를 확인하세요. 보류된 금액은 잔액으로 돌아왔으며, data.retryable은 같은 요청을 다시 보내면 성공할 수 있는지 알려 줍니다.

입력 모드

모드필수 입력참고
텍스트로 이미지 생성model, promptimages를 생략합니다.
이미지 편집·합성model, prompt, images공개 HTTPS 이미지 링크 1~10개. prompt에 바꿀 부분과 유지할 부분을 설명하세요.

요청 파라미터

model string 필수

실행할 모델입니다.

값: qwen-image-2.1

값이 잘못된 경우

  • 누락: "model" is required
  • 알 수 없는 모델 ID: "model" qwen-image-9 is not catalogued
  • 이 엔드포인트로 영상 모델을 보낸 경우: "model" seedance-2.5 is served by POST /v1/videos/tasks, not this endpoint

prompt string 필수

그릴 내용 또는 참조 이미지에서 바꿀 내용입니다. 피사체, 스타일, 조명, 구도, 이미지에 꼭 들어가야 하는 텍스트를 평이한 말로 적는 것이 가장 좋습니다.

길이: 1–5000자

  • 길이는 문자 수로 계산합니다(한중일 문자 하나는 1자).
  • images를 보낼 때는 각 이미지의 역할과 바뀌면 안 되는 부분을 적으세요.
  • enhance_prompt를 켜면 모델이 그리기 전에 프롬프트를 재작성합니다.

값이 잘못된 경우

  • 누락: "prompt" is required
  • 비어 있거나 한도보다 긴 경우: "prompt" has an unsupported length
  • 문자열이 아닌 경우: "prompt" must be a string

images string[] 선택

편집하거나 합성할 참조 이미지입니다. 이 필드를 보내면 요청이 텍스트로 이미지 생성에서 이미지 편집으로 바뀝니다.

항목 수: 1–10
각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

  • 각 링크는 공개 HTTPS로 이미지 파일 자체(PNG, JPEG 또는 WebP, 최대 50 MB)를 반환해야 합니다. 게이트웨이는 작업을 만들기 전에 모든 링크의 앞부분 바이트를 내려받습니다.
  • 웹 페이지, 로그인이 필요한 페이지, 만료된 서명 URL, 핫링크 방지 호스트로 연결되는 링크는 이미지를 반환하지 않으므로 거부됩니다.
  • 오류 메시지의 위치는 0부터 시작합니다. images[0]이 첫 번째 링크입니다.

값이 잘못된 경우

  • 최대 개수를 넘은 경우: "images" accepts at most 10 items
  • 빈 배열: "images" requires at least 1 item
  • https:// 링크가 아닌 경우: "images[0]" must be a public HTTPS URL
  • 비공개 또는 안전하지 않은 주소: "images[0]" must be a publicly reachable HTTPS image URL
  • 호스트가 4xx 오류로 응답한 경우: "images[0]" could not be downloaded: the URL returned HTTP 404
  • 링크가 PNG, JPEG, WebP 이외의 형식을 반환한 경우: "images[0]" is not a PNG, JPEG or WebP image: the URL returned text/html
  • 50 MB보다 큰 경우: "images[2]" is 63.4 MB; images must be 50 MB or smaller

예시

"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png"
]

aspect_ratio string 선택기본값: auto

가로:세로로 나타낸 이미지 모양입니다.

허용 값: auto, 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9, 9:21
기본값: auto

  • auto가 기본값입니다. images가 있으면 출력은 첫 번째 이미지의 모양을 따르고, images가 없으면 auto는 1:1로 렌더링합니다.
  • 편집 결과의 모양을 고정하려면 auto 대신 원하는 비율을 보내세요.

값이 잘못된 경우

  • 목록에 없는 값: "aspect_ratio" must be one of: [auto 1:1 4:3 3:4 3:2 2:3 16:9 9:16 21:9 9:21]

resolution string 선택기본값: 1K

이미지의 크기 등급입니다. 2K는 1K보다 이미지가 크고 가격도 높습니다.

허용 값: 1K, 2K
기본값: 1K

  • 이 모델은 1K와 2K만 있으며 4K는 거부됩니다. 크기 등급은 이 필드에 지정하세요. 프롬프트에 적은 문구로는 등급이 선택되지 않습니다.
  • 대문자 K를 사용하세요. 2k는 거부됩니다.

값이 잘못된 경우

  • 목록에 없는 값(예: 4K): "resolution" must be one of: [1K 2K]

background string 선택기본값: opaque

이미지 배경을 불투명하게 할지 투명하게 할지 정합니다.

허용 값: opaque, transparent
기본값: opaque

  • opaque가 기본값입니다. transparent는 알파 채널이 있는 이미지를 반환하므로 output_format png 또는 webp가 필요합니다.
  • transparent를 보내고 output_format을 생략하면 기본값 png가 사용되어 요청이 수락됩니다.

값이 잘못된 경우

  • 목록에 없는 값(예: auto): "background" must be one of: [opaque transparent]
  • output_format: "jpeg"과 함께 보낸 transparent: Qwen Image 2.1 needs output_format png or webp for a transparent background

enhance_prompt boolean 선택

그리기 전에 모델이 프롬프트를 재작성하도록 합니다.

  • 생략하면 텍스트로 이미지 생성에서는 켜지고 images를 보내면 꺼집니다. 재작성하면 편집 지시 중 유지할 부분이 빠질 수 있기 때문입니다.
  • 기본값과 관계없이 true 또는 false를 보내 직접 지정할 수 있습니다.

값이 잘못된 경우

  • 불리언이 아닌 경우(예: 문자열 "true"): "enhance_prompt" must be a boolean

output_format string 선택기본값: png

결과 파일의 종류입니다.

허용 값: png, webp, jpeg
기본값: png

  • BeatAPI는 PNG와 JPEG 사이에서만 변환합니다. 모델이 두 형식 중 다른 쪽을 반환하면 보통 저장 전에 변환하며(JPEG에서는 투명한 영역이 흰색이 됨), 변환에 실패하면 받은 그대로 저장합니다. WebP로 또는 WebP에서 변환하지는 않습니다.
  • 저장된 형식은 항상 output.media[].mime_type에 표시됩니다. webp를 요청했다면 확인하세요.
  • jpg가 아니라 jpeg으로 쓰세요.

값이 잘못된 경우

  • 목록에 없는 값(예: jpg): "output_format" must be one of: [png webp jpeg]

seed integer 선택

모델에 랜덤 시드로 전달하는 정수입니다. 생략하면 무작위로 정해집니다.

범위: 0–2147483647

  • BeatAPI는 시드와 프롬프트가 같아도 같은 결과를 보장하지 않습니다.

값이 잘못된 경우

  • 정수가 아니거나 음수이거나 2147483647보다 큰 경우: "seed" is outside its supported range

게이트웨이는 작업을 만들기 전에 다음 조합도 검사합니다.

  • aspect_ratio auto는 첫 번째 이미지를 따르며, 이미지가 없으면 1:1로 렌더링합니다
  • enhance_prompt는 렌더링 전에 프롬프트를 재작성합니다. 이미지가 없으면 기본값이 true, 있으면 false입니다. 재작성하면 편집에서 유지하라고 한 부분이 빠질 수 있기 때문입니다
  • background transparent에는 output_format png 또는 webp가 필요합니다

입력 미디어 제한

게이트웨이는 작업을 만들기 전에 모든 입력을 읽고, 아래 제한을 벗어난 입력은 해당 입력을 명시한 400 bad_request로 거부합니다. 과금되지 않습니다.

  • 참조 이미지: PNG, JPEG 또는 WebP이며, 파일 이름이나 Content-Type이 아니라 파일 내용으로 판별합니다. 각각 최대 50 MB(10진 메가바이트 기준, 호스트가 크기를 알려 줄 때 검사), 링크 1~10개. GIF, HEIC, SVG는 거부됩니다.
  • 이 모델은 픽셀이나 화면비 제한을 검사하지 않습니다.
  • 호스트가 제때 응답하지 않으면 작업 생성 시 링크를 거부하지 않습니다. 이후에도 가져올 수 없는 링크는 작업을 실패시키며, 해당 작업은 환불됩니다.
  • 로컬 파일이 있다면 POST /v1/files로 업로드하고 반환된 data.url을 전달하세요.

이 모델이 받지 않는 필드

이미지 엔드포인트는 다른 이미지 모델이 사용하는 필드도 몇 가지 알고 있습니다. 이 모델에서 그런 필드를 보내면 무시하지 않고 거부하므로, 효과 없는 설정에 비용을 내는 일이 없습니다.

  • quality, size → field "quality" is not supported by model qwen-image-2.1(보낸 필드 포함).
  • n 같은 그 밖의 알 수 없는 필드 → unknown field: n. n은 없습니다. 작업 하나에 이미지 한 장입니다.

요청에 잘못된 필드가 여러 개 있어도 메시지에는 하나만 표시됩니다. 고친 뒤 다시 보내세요.

투명 이미지

"background": "transparent"를 output_format png 또는 webp와 함께 보내세요. JPEG에는 알파 채널이 없으므로 transparent와 jpeg을 함께 보내면 아무것도 보류되기 전, 작업 생성 단계에서 거부됩니다. 프롬프트에만 투명 배경을 요청해서는 background가 설정되지 않습니다.

BeatAPI는 WebP로 또는 WebP에서 변환하지 않습니다. 받은 파일 형식은 완료된 작업의 output.media[].mime_type에서 확인하세요.

요청 예시

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A white porcelain crane above misty mountains, ink-wash style, no text"
}'

텍스트로 이미지 생성

프롬프트로 만드는 1K 이미지입니다. 기본값이 적용됩니다(aspect_ratio auto는 1:1로 렌더링, 재작성 켜짐).

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A white porcelain crane above misty mountains, ink-wash style, no text"
}'

이미지 한 장 편집

편집에서는 재작성이 기본적으로 꺼져 있으므로 병을 유지하라는 지시가 적힌 그대로 반영됩니다. auto는 참조 이미지의 모양을 유지합니다.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "Keep the bottle shape and label exactly as they are. Place it on a pale stone counter under soft morning light.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "aspect_ratio": "auto"
}'

투명 WebP

투명 배경 위의 분리된 오브젝트, 2K.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A single green glass perfume bottle, isolated, studio lighting, no text",
  "resolution": "2K",
  "aspect_ratio": "1:1",
  "background": "transparent",
  "output_format": "webp"
}'

재현 가능한 요청

재작성을 끄고 seed를 고정해 프롬프트의 작은 변화를 비교합니다.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A lighthouse on a cliff at dawn, flat illustration, limited palette",
  "aspect_ratio": "3:4",
  "enhance_prompt": false,
  "seed": 42
}'

응답

작업 생성(201)

작업 객체입니다. 작업이 성공할 때까지 output는 null입니다. ‘실행 중’으로 표시된 필드는 작업이 끝나면 사라집니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "qwen-image-2.1",
    "capability_version": 1,
    "media_type": "image",
    "model": "qwen-image-2.1",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 5,
    "output": null,
    "usage": {
      "credits_reserved": 0.01,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.01
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}
필드타입설명
data.idstring작업 ID: task_ 뒤에 영문자와 숫자 32자가 붙습니다. 폴링과 웹훅 이벤트 매칭에 사용합니다.
data.objectstring항상 task.
data.task_kindstringimage 또는 video.
data.capability_idstring보낸 모델 ID입니다.
data.capability_versioninteger모델의 계약 버전으로, 현재 1입니다.
data.media_typestringimage 또는 video.
data.modelstring보낸 모델 ID입니다(capability_id와 같음).
data.statusstringqueued, processing, succeeded 또는 failed. 마지막 두 개만 최종 상태입니다.
data.stagestringstatus와 같은 값으로, 오래된 클라이언트를 위해 유지합니다.
data.created_atinteger작업 생성 시각(Unix 초)입니다.
data.updated_atinteger마지막 변경 시각(Unix 초)입니다.
data.completed_atinteger | null작업 완료 시각(Unix 초)입니다. 실행 중에는 null입니다.
data.poll_after_secondsinteger실행 중: 다음 폴링까지 기다릴 시간입니다(이미지 5, 영상 8).
data.typical_secondsobject실행 중이며 최근 작업이 충분할 때: 최근 window 동안 samples개 작업의 p50 및 p90 완료 시간(초)입니다.
data.outputobject | null결과입니다. status가 succeeded가 될 때까지 null입니다. 아래 출력 필드를 참고하세요.
data.usage.credits_reservednumber작업 생성 시 잔액에서 보류한 USD 금액입니다.
data.usage.credits_chargednumber이 작업의 비용(USD)입니다. 실패한 작업에서는 0입니다.
data.usage.credits_settlednumber최종 청구 금액(USD)입니다. 작업이 성공하면 설정되고, 그렇지 않으면 0입니다.
data.usage.credits_refundednumber잔액으로 환불된 금액(USD)입니다. 실패한 작업에서는 환불이 기록되면 보류 금액과 같아집니다.
data.usage.billable_duration_secondsinteger영상만 해당: 가격 산정의 기준이 되는 초입니다. 모델이 길이를 보고하지 않으면 없습니다.
data.request_idstring요청 ID입니다. 지원팀에 문의할 때 함께 알려 주세요.
data.error_codestring | null실패 코드입니다. 작업이 실패하지 않았다면 null입니다.
data.error_messagestring | null무엇이 잘못되었고 무엇을 바꿔야 하는지 설명합니다. 작업이 실패하지 않았다면 null입니다.

완료된 작업

GET /v1/tasks/{task_id}는 HTTP 200과 함께 status: "succeeded", 그리고 data.output에 결과를 반환합니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "qwen-image-2.1",
    "capability_version": 1,
    "media_type": "image",
    "model": "qwen-image-2.1",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "image",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png",
          "mime_type": "image/png"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png"
    },
    "usage": {
      "credits_reserved": 0.01,
      "credits_settled": 0.01,
      "credits_refunded": 0,
      "credits_charged": 0.01
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

출력 필드

필드타입설명
output.mediaobject[]생성된 파일입니다. 이 모델은 항목이 하나입니다.
output.media[].typestring항상 image.
output.media[].urlstring저장된 이미지의 HTTPS 링크입니다. 다운로드해 보관하세요. 보관 기간은 보장되지 않습니다.
output.media[].mime_typestring저장된 파일 형식이며 image/png, image/jpeg 또는 image/webp입니다. 보통 output_format에서 요청한 형식입니다.
output.r2_urlstring오래된 클라이언트를 위해 첫 번째 미디어 URL을 한 번 더 담습니다. 대신 media를 사용하세요.

실패한 작업

실패한 작업도 GET /v1/tasks/{task_id}에서는 HTTP 200입니다. 실패 정보는 본문에 있습니다. 보류 금액이 전액 환불되므로 과금되지 않습니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "qwen-image-2.1",
    "capability_version": 1,
    "media_type": "image",
    "model": "qwen-image-2.1",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.01,
      "credits_settled": 0,
      "credits_refunded": 0.01,
      "credits_charged": 0
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}
필드타입설명
data.error_codestringbad_request, content_policy_violation(요청 수정 필요) 또는 processing_unavailable, processing_timeout, processing_failed, result_transfer_failed(나중에 재시도) 중 하나입니다. 오류를 참고하세요.
data.error_messagestring문제와 해결 방법을 설명하는 문장입니다.
data.retryableboolean실패한 작업에만 있습니다. 같은 요청을 다시 보내면 성공할 수 있을 때 true입니다.
data.usageobject환불이 기록되면(보통 작업이 실패하는 시점): credits_charged와 credits_settled는 0이고, credits_refunded는 credits_reserved와 같습니다.

전체 예시

작업을 만들고, 서버의 폴링 안내에 따라 기다린 뒤 결과 URL을 출력합니다. 환경 변수에 BEATAPI_API_KEY를 설정하고 requests를 설치하세요.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/images/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "qwen-image-2.1",
  "prompt": "A white porcelain crane above misty mountains, ink-wash style, no text"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

과금

  • 작업 하나에 이미지 한 장이며, resolution에 따라 가격이 정해집니다(아래 표). 가격표에는 해상도별로 행이 하나씩 있으며, 참조 이미지·투명도·프롬프트 재작성에 대한 별도 요금은 없습니다.
  • 가격은 작업 생성 시 잔액에서, 키에 한도가 있다면 키 한도에서도 보류됩니다. 작업이 생기기 전에 거부된 요청은 비용이 들지 않습니다.
  • 성공한 작업은 보류 금액이 그대로 청구됩니다. 실패한 작업은 전액 환불되어 credits_refunded가 credits_reserved와 같아지고, credits_charged와 credits_settled는 0이 됩니다.

현재 정가이며 가격 페이지와 같습니다. 별도 할인 계약이 있는 계정은 더 적게 지불하며, 실제 청구 금액은 항상 작업의 data.usage에서 확인할 수 있습니다.

옵션정가(USD)
이미지 1장 · 1K$0.01
이미지 1장 · 2K$0.05

자주 발생하는 오류

오류 또는 증상원인해결 방법
400 Qwen Image 2.1 needs output_format png or webp for a transparent backgroundoutput_format: "jpeg"과 함께 보낸 background: "transparent".png 또는 webp를 사용하거나 output_format을 생략하세요.
400 "resolution" must be one of: [1K 2K]4K 또는 소문자 2k.1K 또는 2K를 보내세요.
400 "seed" is outside its supported range음수(예: “무작위” 의미로 쓴 -1), 소수, 문자열 또는 2147483647보다 큰 값.0~2147483647 사이의 정수를 보내거나, 무작위로 하려면 seed를 생략하세요.
400 "enhance_prompt" must be a booleanJSON 불리언 대신 문자열 "true" 또는 "false"를 보냈습니다.따옴표 없이 true 또는 false를 보내세요.
400 "background" must be one of: [opaque transparent]Qwen Image 2.1에 auto 또는 다른 값을 보냈습니다.opaque 또는 transparent를 보내세요.
400 field "quality" is not supported by model qwen-image-2.1다른 이미지 모델의 필드(quality, size)를 보냈습니다.해당 필드를 삭제하세요.
400 unknown field: n작업 하나에서 이미지 여러 장을 요청했습니다.n을 삭제하고 이미지마다 작업을 하나씩 만드세요.
400 "images[1]" is not a PNG, JPEG or WebP image: the URL returned text/html링크가 파일 대신 웹 페이지, 로그인 페이지 또는 만료된 서명 URL을 엽니다.이미지 파일로 직접 연결되는 링크를 사용하세요.
400 "images[0]" could not be downloaded: the URL returned HTTP 403호스트가 서버의 다운로드를 차단합니다(핫링크 방지 또는 비공개 버킷).파일을 공개하거나 POST /v1/files로 업로드하세요.
400 aspect_ratio "21:9" is not available for this model right now; available: …현재 이 모델을 제공하는 라인 중 해당 조합을 받는 라인이 없습니다.목록에 있는 값을 사용하거나 나중에 다시 시도하세요.
aspect_ratio를 생략했는데 텍스트로 이미지 생성 결과가 정사각형입니다참조 이미지가 없으면 기본값 auto는 1:1로 렌더링합니다.원하는 비율을 지정하세요(예: 16:9).
편집 결과에서 프롬프트가 유지하라고 한 부분이 빠졌습니다enhance_prompt: true를 보내 그리기 전에 프롬프트가 재작성되었습니다.enhance_prompt를 생략하거나(편집에서는 꺼져 있음) false를 보내세요.
작업이 content_policy_violation과 함께 failed프롬프트, 참조 이미지 또는 생성된 이미지가 콘텐츠 검수에서 거부되었습니다.프롬프트나 이미지를 바꾸세요. 그대로 재시도하면 다시 실패하며, 과금되지 않습니다.
작업이 processing_timeout과 함께 failed처리 제한 시간 안에 이미지가 완성되지 않았습니다.재시도하세요. 실패한 작업은 환불되었습니다.
한 번도 충전하지 않은 계정에서 403 forbidden무료 크레딧은 일부 모델에서만 사용할 수 있습니다.한 번 충전하거나, 무료 크레딧으로 사용할 수 있는 모델을 사용하세요.

HTTP 오류 요약

작업이 생성되기 전의 오류는 2xx가 아닌 응답으로 오며 과금되지 않습니다. error.code 또는 error.retryable로 분기하세요. message에 문제가 표시됩니다. 전체 목록과 재시도 정책은 오류에 있습니다.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}
HTTP 상태error.code조치
400bad_request, content_policy_violation요청을 수정하세요. 메시지에 해당 필드가 표시됩니다. 그대로 재시도하지 마세요.
401missing_api_key, invalid_api_key(오래된 클라이언트에서는 unauthorized가 보일 수 있음)유효한 키를 Authorization: Bearer <key>로 보내세요.
402insufficient_credits충전하거나 키 한도를 올린 뒤 다시 보내세요.
403forbidden이 키나 계정으로는 이 모델을 사용할 수 없습니다(예: 무료 크레딧은 일부 모델만 지원). 그대로 재시도하지 마세요.
404not_foundGET /v1/tasks/{task_id}에서: 이 키의 계정에 해당 작업이 없습니다. ID를 확인하세요.
409idempotency_conflict새 Idempotency-Key를 사용하거나, 이 키를 쓴 첫 요청이 끝날 때까지 기다리세요.
429rate_limit_exceededRetry-After에 표시된 시간(또는 error.retry_after_seconds초)만큼 기다린 뒤 재시도하세요.
500internal_error백오프를 적용해 재시도하고, 계속되면 request_id와 함께 지원팀에 문의하세요.
503processing_unavailable, processing_timeout, processing_failed, result_transfer_failed과금되지 않았습니다. 지수 백오프를 적용해 재시도하세요.

인증

AuthorizationBearer

API 키를 Authorization: Bearer <BEATAPI_API_KEY>로 보내세요.

헤더

Idempotency-Keystring선택 사항<=255 characters

본문은 Content-Type: application/json과 함께 JSON으로 보냅니다. Idempotency-Key는 선택 사항입니다. 논리적 요청마다 고유한 값(최대 255자)을 보내고, 완전히 같은 본문을 재시도할 때만 다시 사용하세요. 24시간 안에 같은 키와 본문으로 재시도하면 첫 응답을 Idempotent-Replayed: true와 함께 다시 반환하고, 같은 키에 다른 본문을 보내면 409 idempotency_conflict를 반환합니다. 2xx 이외의 응답은 저장되지 않으므로 400이나 402 이후의 재시도는 다시 실행됩니다.

요청

This endpoint expects an object.
modelenum필수

실행할 모델입니다.

값: qwen-image-2.1

값이 잘못된 경우

  • 누락: "model" is required
  • 알 수 없는 모델 ID: "model" qwen-image-9 is not catalogued
  • 이 엔드포인트로 영상 모델을 보낸 경우: "model" seedance-2.5 is served by POST /v1/videos/tasks, not this endpoint
허용된 값:
promptstring필수1-5000 characters

그릴 내용 또는 참조 이미지에서 바꿀 내용입니다. 피사체, 스타일, 조명, 구도, 이미지에 꼭 들어가야 하는 텍스트를 평이한 말로 적는 것이 가장 좋습니다.

길이: 1–5000자

  • 길이는 문자 수로 계산합니다(한중일 문자 하나는 1자).
  • images를 보낼 때는 각 이미지의 역할과 바뀌면 안 되는 부분을 적으세요.
  • enhance_prompt를 켜면 모델이 그리기 전에 프롬프트를 재작성합니다.

값이 잘못된 경우

  • 누락: "prompt" is required
  • 비어 있거나 한도보다 긴 경우: "prompt" has an unsupported length
  • 문자열이 아닌 경우: "prompt" must be a string
aspect_ratioenum선택 사항기본값 auto

가로:세로로 나타낸 이미지 모양입니다.

허용 값: auto, 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9, 9:21

기본값: auto

  • auto가 기본값입니다. images가 있으면 출력은 첫 번째 이미지의 모양을 따르고, images가 없으면 auto는 1:1로 렌더링합니다.
  • 편집 결과의 모양을 고정하려면 auto 대신 원하는 비율을 보내세요.

값이 잘못된 경우

  • 목록에 없는 값: "aspect_ratio" must be one of: [auto 1:1 4:3 3:4 3:2 2:3 16:9 9:16 21:9 9:21]
backgroundenum선택 사항기본값 opaque

이미지 배경을 불투명하게 할지 투명하게 할지 정합니다.

허용 값: opaque, transparent

기본값: opaque

  • opaque가 기본값입니다. transparent는 알파 채널이 있는 이미지를 반환하므로 output_format png 또는 webp가 필요합니다.
  • transparent를 보내고 output_format을 생략하면 기본값 png가 사용되어 요청이 수락됩니다.

값이 잘못된 경우

  • 목록에 없는 값(예: auto): "background" must be one of: [opaque transparent]
  • output_format: "jpeg"과 함께 보낸 transparent: Qwen Image 2.1 needs output_format png or webp for a transparent background
허용된 값:
enhance_promptboolean선택 사항

그리기 전에 모델이 프롬프트를 재작성하도록 합니다.

  • 생략하면 텍스트로 이미지 생성에서는 켜지고 images를 보내면 꺼집니다. 재작성하면 편집 지시 중 유지할 부분이 빠질 수 있기 때문입니다.
  • 기본값과 관계없이 true 또는 false를 보내 직접 지정할 수 있습니다.

값이 잘못된 경우

  • 불리언이 아닌 경우(예: 문자열 "true"): "enhance_prompt" must be a boolean
imageslist of strings선택 사항

편집하거나 합성할 참조 이미지입니다. 이 필드를 보내면 요청이 텍스트로 이미지 생성에서 이미지 편집으로 바뀝니다.

항목 수: 1–10

각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

  • 각 링크는 공개 HTTPS로 이미지 파일 자체(PNG, JPEG 또는 WebP, 최대 50 MB)를 반환해야 합니다. 게이트웨이는 작업을 만들기 전에 모든 링크의 앞부분 바이트를 내려받습니다.
  • 웹 페이지, 로그인이 필요한 페이지, 만료된 서명 URL, 핫링크 방지 호스트로 연결되는 링크는 이미지를 반환하지 않으므로 거부됩니다.
  • 오류 메시지의 위치는 0부터 시작합니다. images[0]이 첫 번째 링크입니다.

값이 잘못된 경우

  • 최대 개수를 넘은 경우: "images" accepts at most 10 items
  • 빈 배열: "images" requires at least 1 item
  • https:// 링크가 아닌 경우: "images[0]" must be a public HTTPS URL
  • 비공개 또는 안전하지 않은 주소: "images[0]" must be a publicly reachable HTTPS image URL
  • 호스트가 4xx 오류로 응답한 경우: "images[0]" could not be downloaded: the URL returned HTTP 404
  • 링크가 PNG, JPEG, WebP 이외의 형식을 반환한 경우: "images[0]" is not a PNG, JPEG or WebP image: the URL returned text/html
  • 50 MB보다 큰 경우: "images[2]" is 63.4 MB; images must be 50 MB or smaller

예시

"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png"
]
output_formatenum선택 사항기본값 png

결과 파일의 종류입니다.

허용 값: png, webp, jpeg

기본값: png

  • BeatAPI는 PNG와 JPEG 사이에서만 변환합니다. 모델이 두 형식 중 다른 쪽을 반환하면 보통 저장 전에 변환하며(JPEG에서는 투명한 영역이 흰색이 됨), 변환에 실패하면 받은 그대로 저장합니다. WebP로 또는 WebP에서 변환하지는 않습니다.
  • 저장된 형식은 항상 output.media[].mime_type에 표시됩니다. webp를 요청했다면 확인하세요.
  • jpg가 아니라 jpeg으로 쓰세요.

값이 잘못된 경우

  • 목록에 없는 값(예: jpg): "output_format" must be one of: [png webp jpeg]
허용된 값:
resolutionenum선택 사항기본값 1K

이미지의 크기 등급입니다. 2K는 1K보다 이미지가 크고 가격도 높습니다.

허용 값: 1K, 2K

기본값: 1K

  • 이 모델은 1K와 2K만 있으며 4K는 거부됩니다. 크기 등급은 이 필드에 지정하세요. 프롬프트에 적은 문구로는 등급이 선택되지 않습니다.
  • 대문자 K를 사용하세요. 2k는 거부됩니다.

값이 잘못된 경우

  • 목록에 없는 값(예: 4K): "resolution" must be one of: [1K 2K]
허용된 값:
seedinteger선택 사항0-2147483647

모델에 랜덤 시드로 전달하는 정수입니다. 생략하면 무작위로 정해집니다.

범위: 0–2147483647

  • BeatAPI는 시드와 프롬프트가 같아도 같은 결과를 보장하지 않습니다.

값이 잘못된 경우

  • 정수가 아니거나 음수이거나 2147483647보다 큰 경우: "seed" is outside its supported range

응답

작업 객체입니다. 작업이 성공할 때까지 output는 null입니다. ‘실행 중’으로 표시된 필드는 작업이 끝나면 사라집니다.

오류

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error