이미지

이미지를 만드는 엔드포인트는 두 개입니다.

• POST /v1/images/generations 엔드포인트는 텍스트 프롬프트로 이미지를 생성합니다.
• POST /v1/images/edits 엔드포인트는 텍스트 프롬프트로 참조 이미지 하나 이상을 편집합니다.

두 엔드포인트 모두 Authorization: Bearer로 보내는 API 키가 필요합니다. 인증을 참고하세요. 본문은 JSON입니다. multipart 업로드는 지원하지 않으므로 참조 이미지는 JSON 안에 URL이나 데이터 URI로 보냅니다.

모든 이미지 요청은 작업으로 실행됩니다. 요청이 작업을 기다렸다가 응답에 이미지를 담아 반환할 수도 있고, 작업을 즉시 반환해 나중에 결과를 받게 할 수도 있습니다.

모델과 프롬프트를 보냅니다. 이 예시에서 사용하는 모델은 sakuranbo/cherryimage-1.0-pro입니다.

curl -X POST "https://api.sakuranbo.ai/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY" \
  -d '{
  "model": "sakuranbo/cherryimage-1.0-pro",
  "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
  "resolution": "2k",
  "aspect_ratio": "4:3"
}'

const response = await fetch("https://api.sakuranbo.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
  body: JSON.stringify({
    "model": "sakuranbo/cherryimage-1.0-pro",
    "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
    "resolution": "2k",
    "aspect_ratio": "4:3"
  }),
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.post(
    "https://api.sakuranbo.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
    json={
        "model": "sakuranbo/cherryimage-1.0-pro",
        "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
        "resolution": "2k",
        "aspect_ratio": "4:3",
    },
)
print(response.json())

예시 모델의 입력 파라미터는 다음과 같습니다.

요청 본문에는 다음 필드가 있습니다.

resolution이 가격을 정합니다. 표에 없는 파라미터나 범위를 벗어난 값은 400과 invalid_request를 반환합니다. error.param이 파라미터의 이름을 알려 주고, error.details.allowed, error.details.minimum, error.details.maximum이 유효한 값을 알려 줍니다.

기본적으로 요청은 이미지가 만들어질 때까지 기다립니다.

• 작업이 최대 대기 시간 안에 끝나면 응답은 이미지가 담긴 200입니다. 대기 시간은 API 레퍼런스에 나와 있습니다.
• 그 시간이 지나도 작업이 실행 중이면 응답은 작업과, 작업을 가리키는 Location 헤더가 담긴 202입니다. 생성은 계속 실행됩니다.
• Prefer: respond-async를 보내면 응답은 즉시 202이며, 응답에 Preference-Applied: respond-async 헤더가 있습니다.

curl -X POST "https://api.sakuranbo.ai/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY" \
  -H "Prefer: respond-async" \
  -d '{
  "model": "sakuranbo/cherryimage-1.0-pro",
  "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
  "resolution": "2k",
  "aspect_ratio": "4:3"
}'

const response = await fetch("https://api.sakuranbo.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
    Prefer: "respond-async",
  },
  body: JSON.stringify({
    "model": "sakuranbo/cherryimage-1.0-pro",
    "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
    "resolution": "2k",
    "aspect_ratio": "4:3"
  }),
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.post(
    "https://api.sakuranbo.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
        "Prefer": "respond-async",
    },
    json={
        "model": "sakuranbo/cherryimage-1.0-pro",
        "prompt": "A matte ceramic coffee mug on a walnut desk, soft morning light, shallow depth of field",
        "resolution": "2k",
        "aspect_ratio": "4:3",
    },
)
print(response.json())

202 응답을 받은 뒤에는 두 가지 방법으로 결과를 받습니다. 작업에 설명된 대로 작업을 폴링하거나, 웹훅에 설명된 대로 job.succeeded, job.failed, job.cancelled 이벤트를 받습니다.

요청이 기다리는 동안 작업이 실패하면 응답은 202가 아니라 오류이며, error.details.job_id가 작업의 ID입니다. 202 응답을 받은 뒤의 실패는 작업의 error 필드에 나타나고, 작업을 읽는 요청은 그래도 200을 반환합니다.

200 응답에는 다음 필드가 있습니다.

cost는 최종 청구액입니다. 같은 금액이 X-Usage-Cost-Usd 헤더에도 들어 있습니다. job_id는 이미지를 만든 작업의 ID입니다.

response_format으로 이미지를 돌려받는 방식을 선택합니다.

• url이 기본값입니다. data의 각 항목에 url과 expires_at이 있습니다. URL은 서명되어 있고 API 키가 필요하지 않으며 expires_at까지 유효합니다. expires_at은 작업이 완료된 지 7일 뒤의 시각입니다. URL을 아는 사람은 누구나 그때까지 이미지를 내려받을 수 있으므로 URL을 비밀로 취급하세요. expires_at이 지나면 파일이 삭제되므로 필요한 이미지는 저장해 두세요.
• b64_json은 이미지를 base64로 응답 본문에 담습니다. 이미지가 너무 커서 본문에 담을 수 없으면, 담지 못한 이미지는 url 항목으로 돌아옵니다.

data에는 전달된 이미지마다 항목이 하나씩 있습니다. 일괄 생성의 일부가 실패하면 data의 항목이 n보다 적을 수 있으며, 전달된 이미지에 대해서만 요금이 청구됩니다.

POST /v1/images/edits 엔드포인트는 생성 엔드포인트와 같은 필드를 받으며, images 필드가 필수입니다.

curl -X POST "https://api.sakuranbo.ai/v1/images/edits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY" \
  -d '{
  "model": "sakuranbo/cherryimage-1.0-pro",
  "prompt": "Make the mug dark blue",
  "images": [
    "https://example.com/reference.png"
  ]
}'

const response = await fetch("https://api.sakuranbo.ai/v1/images/edits", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
  body: JSON.stringify({
    "model": "sakuranbo/cherryimage-1.0-pro",
    "prompt": "Make the mug dark blue",
    "images": [
      "https://example.com/reference.png"
    ]
  }),
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.post(
    "https://api.sakuranbo.ai/v1/images/edits",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
    json={
        "model": "sakuranbo/cherryimage-1.0-pro",
        "prompt": "Make the mug dark blue",
        "images": [
            "https://example.com/reference.png",
        ],
    },
)
print(response.json())

images는 참조 이미지의 목록입니다. 각 항목은 PNG, JPEG, WebP, GIF 이미지의 공개 https URL이거나 data:image/...;base64, URI입니다. 프롬프트가 첫 번째 이미지나 두 번째 이미지를 가리킬 수 있으므로 순서가 중요합니다. 데이터 URI는 URL보다 크기 제한이 작으므로 큰 이미지는 공개 URL로 보내세요.

서버는 작업을 만들기 전에 각 URL을 가져와 확인합니다. 리다이렉트를 따라가지 않으며, 자격 증명, IP 주소, 내부 호스트 이름이 들어 있는 URL은 거부합니다. 사용할 수 없는 이미지는 400과 invalid_request를 반환합니다. error.param은 images 뒤에 항목의 인덱스가 붙은 값입니다. URL이면 error.details.reason이 무엇이 잘못되었는지 알려 줍니다. 데이터 URI가 너무 크면 error.details.max_bytes가 허용 크기입니다.

응답은 생성과 같습니다.

원하는 값으로 Idempotency-Key 헤더를 보내세요. 같은 키와 같은 내용의 요청이 다시 오면 같은 작업을 받고 요금은 한 번만 청구됩니다. 같은 키로 다른 요청을 보내면 409와 idempotency_conflict가 반환됩니다. 키는 한정된 시간 동안 기억되며, 그 시간은 API 레퍼런스에 나와 있습니다.

요청이 받아들여지면 Sakuranbo AI는 요청한 이미지의 가격만큼을 잔액에서 확보합니다. 작업이 끝나면 전달된 이미지에 대한 청구액을 계산하고, 확보했던 금액의 나머지는 잔액으로 돌아옵니다. 취소되거나 만료되거나 거부된 작업은 과금되지 않습니다. 실패한 작업도 보통은 과금되지 않으며, 확보했던 금액은 잔액으로 돌아옵니다.

드물게 Sakuranbo AI가 요청이 모델 제공업체에 도달했는지 확인하지 못하는 경우가 있습니다. 이때 작업은 upstream_error와 함께 실패하고, 확보한 금액은 Sakuranbo AI가 과금 여부를 확인할 때까지 확보된 상태로 남습니다. 계속 남아 있다면 작업 ID와 함께 지원팀에 문의하세요.

가격은 모델, resolution, 이미지 수에 따라 달라집니다. 모델 카탈로그와 요금 페이지를 보거나, 요청을 실행하기 전에 POST /v1/estimate 엔드포인트로 계산하세요. 비용 계산 API를 참고하세요.

모델 제공업체가 프롬프트, 참조 이미지 또는 생성된 이미지를 그 내용을 이유로 거부할 수 있습니다. 이 경우 작업은 content_policy_violation으로 실패하고 요금은 청구되지 않습니다. 작업을 기다리는 요청은 이 코드와 422를 반환하며, error.details.job_id가 작업의 ID입니다. 202 응답을 받은 뒤에는 작업의 error 필드에 이 코드가 들어 있습니다.

POST /v1/images/edits 엔드포인트도 같은 코드를 반환합니다. 429나 503 응답을 받으면 Retry-After 헤더에 표시된 초만큼 기다린 뒤 다시 시도하세요. 402 응답에는 balance 또는 key인 error.details.limit_source가 있습니다. 잔액과 API 키 사용 한도를 참고하세요. 전체 코드 목록은 오류를 참고하세요.