이미지

보낼 수 있는 것Copy Anchor Link

이 규칙을 어기는 파일은 차감 전에 400 invalid_image로 거절됩니다.

이미지를 보내는 네 가지 방법Copy Anchor Link

요청마다 정확히 하나만 사용합니다. 아무것도 보내지 않거나 둘 이상 보내면 400 invalid_request가 반환됩니다.

1. image_urlCopy Anchor Link

공개된 http(s) 링크. 요청을 처리하는 동안 한 번 다운로드하므로, 서명된 링크는 우리가 응답할 때까지만 유효하면 됩니다. 리디렉션은 최대 3번 따라가고 15초 뒤에 포기합니다. 파일을 다운로드할 수 없으면 400 invalid_image가 반환됩니다. 쿠키나 로그인이 필요한 링크, 그리고 localhost, 10.x.x.x, 192.168.x.x 같은 사설 네트워크 주소는 사용할 수 없습니다.

{ "image_url": "https://example.com/banner.png" }

2. image_base64Copy Anchor Link

파일 바이트를 표준 base64(A–Z a–z 0–9 + /, 패딩은 선택)로 인코딩한 것, 또는 같은 내용의 data URL(미디어 타입 무관)입니다. 예를 들어 data:image/png;base64,나 브라우저의 FileReader가 만들 수 있는 data:application/octet-stream;base64,도 됩니다. 형식은 바이트로 판별합니다. 공백과 줄바꿈은 무시되므로 Linux의 base64나 Python의 base64.encodebytes가 만드는 76자 줄도 그대로 쓸 수 있습니다. base64는 파일을 약 3분의 1 크게 만들므로 JSON 본문 전체는 최대 28 MB까지 가능합니다. 더 큰 본문은 400 invalid_image를 반환합니다. 유효한 base64가 아닌 텍스트는 400 invalid_request, 유효한 base64지만 지원하지 않는 이미지인 파일은 400 invalid_image를 반환합니다.

{ "image_base64": "iVBORw0KGgoAAAANSUhEUgAA..." }
{ "image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }

3. 멀티파트 파일 업로드Copy Anchor Link

multipart/form-data로 보내고 파일은 image 필드에 넣습니다. POST /edits에서는 replacements 배열을 JSON 문자열로 폼 필드에 넣습니다. match, language, callback_url은 일반 폼 필드입니다.

curl https://api.rewords.ai/v1/edits \
  -H "Authorization: Bearer $REWORDS_API_KEY" \
  -F [email protected] \
  -F 'replacements=[{"from":"SALE","to":"HOT DEAL"}]'

import crypto from 'node:crypto';
import fs from 'node:fs';

const form = new FormData();
form.append('image', new Blob([await fs.promises.readFile('banner.png')]), 'banner.png');
form.append('replacements', JSON.stringify([{ from: 'SALE', to: 'HOT DEAL' }]));
const res = await fetch('https://api.rewords.ai/v1/edits', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.REWORDS_API_KEY}`, // let fetch set the multipart Content-Type
    'Idempotency-Key': crypto.randomUUID(), // a new key per job; reuse it only to resend this same job
  },
  body: form,
});
const job = await res.json();
if (!res.ok) throw new Error(`${res.status} ${job.error.code}: ${job.error.message}`);
console.log(job.id, job.status);

4. image_idCopy Anchor Link

POST /ocr는 image_id를 반환합니다. 24시간 안에 이를 POST /edits에 넘기면 이미지를 다시 보내지 않고 업로드된 이미지를 재사용할 수 있습니다. 만든 계정에서만 쓸 수 있으며, 알 수 없거나 만료되었거나 다른 계정의 id는 400 invalid_request를 반환합니다. OCR을 호출할 때마다 새 image_id가 반환됩니다. 이전에 보낸 이미지여도 마찬가지이며, image_id를 POST /ocr에 보낸 경우에도 새로 24시간을 받습니다.

이미지를 읽는 방식Copy Anchor Link

• EXIF 방향을 먼저 적용합니다. 옆으로 저장된 휴대폰 사진은 똑바로 세워지며, 모든 width, height와 상자는 세운 뒤의 이미지(이미지 뷰어에서 보이는 모습)를 기준으로 합니다.
• 투명한 영역은 흰색이 됩니다. 결과가 JPEG이므로 PNG와 WebP의 투명도는 흰 배경 위에 합쳐집니다.

결과Copy Anchor Link

• results.A.url, results.B.url, results.C.url은 공개 링크의 JPEG 파일입니다. 일반 GET으로 다운로드하며 API 키는 필요 없습니다. 링크를 가진 사람은 누구나 열 수 있으니 비공개로 다루세요.
• 다운로드할 때 User-Agent 헤더를 보내세요. Python urllib의 기본값은 403으로 거부됩니다. requests, curl, 브라우저, Node fetch는 그대로 동작합니다.
• 링크는 최소 7일 보관됩니다. 보관할 것은 다운로드하세요.
• 결과 파일은 EXIF 방향 없이 똑바로 저장되므로 파일의 크기가 보이는 크기입니다.
• B는 원본 이미지에 새 텍스트를 자연스럽게 합친 것입니다. A는 AI가 이미지 전체를 다시 그린 것으로, 이미지의 가로세로 비율을 유지합니다. 업로드와 같다고 가정하지 말고 픽셀 크기는 파일에서 읽으세요.
• C(4K)는 최대 약 830만 화소(3840 × 2160 상당), 긴 변은 최대 3840 px, 같은 비율입니다. 가로나 세로가 3:1보다 긴 이미지에서는 만들지 않습니다.

상자와 픽셀Copy Anchor Link

상자는 [x, y, width, height]이며, 세운 뒤의 이미지에 대한 0–1000 척도의 정수로 왼쪽 위 모서리부터 잽니다. width와 height는 최소 1이고, x + width와 y + height는 1000을 넘지 않습니다.

pixel left   = x      / 1000 * imageWidth
pixel top    = y      / 1000 * imageHeight
pixel width  = width  / 1000 * imageWidth
pixel height = height / 1000 * imageHeight

예: 1080 × 1350 이미지에서 상자 [120, 80, 300, 60]은 왼쪽 130, 위 108, 324 × 81 px(반올림)입니다. 직접 상자를 보내려면 반대로 변환한 뒤 정수로 반올림하세요.