이미지와 영상 만들기
만들려는 결과에 맞는 엔드포인트와 모델 가이드 찾기
이미지 생성, 이미지 편집과 영상 생성 엔드포인트가 결과를 돌려주는 방법과 모델별 호출 경로를 설명하고, 동기 호출과 비동기 호출을 비교합니다.
페이지 목차
지원 범위
AI 게이트웨이로는 프롬프트로 새 이미지를 만들거나, 편집할 이미지와 프롬프트를 보내 이미지를 바꿀 수 있습니다. 영상은 프롬프트로 만들 수 있고, 모델에 따라 이미지, 영상 또는 오디오 참조를 함께 보낼 수 있습니다. 엔드포인트마다 결과를 돌려주는 방법과 쓸 수 있는 기능이 다릅니다.
| 엔드포인트 | 만드는 것 | 결과를 받는 방법 | 작업 조회와 비동기 요청 |
|---|---|---|---|
Image Generations POST /v1/images/generations (JSON) | 프롬프트로 새 이미지. 모델에 따라 참조 이미지로 편집 | 모델에 따라 둘 중 하나. 응답 본문의 base64 이미지, 또는 응답의 이미지 URL과 작업 ID | 작업 ID를 반환하는 모델에서 지원. 작업 ID로 Jobs에서 다시 조회, Prefer: respond-async로 비동기 요청, 웹훅 알림 |
Image Edits POST /v1/images/edits (multipart/form-data) | 입력 이미지의 편집 | 응답 본문의 base64 이미지 | 지원하지 않음 |
Chat Completions POST /v1/chat/completions | 이미지(이미지 생성을 지원하는 모델) | 응답 본문의 이미지 | 지원하지 않음 |
Video Generations POST /v1/video/generations | 영상 | 접수 응답의 작업 ID로 Jobs를 조회한 뒤 다운로드 링크를 발급받음 | 모든 요청이 작업 ID를 반환함 |
각 엔드포인트의 요청과 응답은 Image Generations, Image Edits, Video Generations 명세에 있습니다.
모델별 호출 경로
모델마다 쓰는 엔드포인트가 다르므로, 모델 이름이나 결과 종류만 보고 엔드포인트를 정하지 마세요. 사용할 모델의 엔드포인트와 기능을 아래 표에서 찾고, 요청 본문은 모델 가이드를 보고 작성합니다.
| 모델 | 엔드포인트 | 기능 | 요청을 쓸 때 볼 곳 |
|---|---|---|---|
GPT Image 2 (gpt-image-2) | 생성은 Image Generations, 편집은 Image Edits | 결과를 응답 본문의 data[].b64_json으로 받음. 모든 스페이스에 기본 제공되며 처음 이미지를 만들 때 쓸 수 있음 | GPT Image 2 가이드 |
| Seedream 5.5 | 생성과 편집 모두 Image Generations | 작업 ID를 반환함. 동기 응답의 작업 ID로 Jobs에서 다시 조회할 수 있음. 비동기 요청, 웹훅과 레이어 분해 지원 | Seedream 5.5 가이드 |
| Gemini 이미지 모델 | Chat Completions | 일반 요청처럼 messages에 프롬프트를 보내고, 결과를 동기 응답의 choices[0].message.images[]로 받음. 현재 모델 코드는 에셋에서 확인 | Chat Completions의 이미지 생성 결과 |
| Seedance 2.5, Seedance 2.0 계열 | Video Generations | 작업 ID를 반환함. 마지막 프레임을 받아 다음 영상의 첫 프레임으로 쓸 수 있음 | Seedance 2.5 가이드, Seedance 2.0 계열 가이드 |
| Kling | Video Generations | 작업 ID를 반환함. 호환 기간 동안 이전 Kling 전용 필드 이름도 받음 | Kling 가이드, 이전 필드 이름 |
현재 스페이스에서 사용할 수 있는 모델과 모델 코드, 단가는 에셋에서 확인합니다. 영상 모델은 에셋 화면의 미디어 모델 탭에 있습니다. 이미지 모델 가운데 일부는 기본 모델 탭에 있으므로, 찾는 모델이 미디어 모델 탭에 없으면 기본 모델 탭을 확인하세요.
같은 엔드포인트를 쓰더라도 모델마다 다른 것이 있습니다.
| 구분 | 해당하는 내용과 확인할 곳 |
|---|---|
| 필드 이름은 같지만 허용 값이 모델마다 다름 | 요청 본문의 필드. 모델마다 지원하는 필드, 허용 값과 기본값, 함께 사용할 수 있는 입력이 다름. 각 모델 가이드의 요청 필드와 허용 값 절에 있음 |
| 한 모델에서만 사용할 수 있음 | 한 모델이나 한 모델 계열에만 있는 기능. 예: 마지막 프레임으로 다음 영상 만들기. 각 모델 가이드에 있음 |
요청 본문을 쓸 때는 다음을 지키세요.
- 한 모델의 본문을 다른 모델에 그대로 보내지 마세요. 모델 가이드에 없는 필드를 보내거나 값의 타입이나 범위가 맞지 않으면 요청이 거절됩니다. 이미지 모델과 영상 모델 모두 같습니다.
- 영상 모델에 새로 연동할 때는 렛서 필드 이름을 쓰세요. 여러 모델에서 이름이 같은 필드도 그 절에 모여 있습니다.
동기 호출과 비동기 호출
결과를 받는 방법은 엔드포인트와 모델의 기능에 따라 동기 호출과 비동기 호출로 나뉩니다.
- 동기 호출: 결과를 응답으로 바로 받습니다. Image Edits, Chat Completions의 이미지 생성, 결과를 응답 본문으로 받는 모델의 Image Generations가 여기에 해당합니다. 작업 ID를 반환하는 모델에
Prefer: respond-async헤더 없이 보낸 Image Generations 요청도 동기 호출입니다. 이때 응답에 작업 ID가 함께 들어 있어 같은 결과를 Jobs에서 다시 조회할 수 있습니다. - 비동기 호출: 게이트웨이가 요청을 작업으로 접수하고 작업 ID를 돌려줍니다. 결과는 그 작업 ID로 Jobs에서 조회합니다. 모든 Video Generations 요청과, 작업 ID를 반환하는 모델에
Prefer: respond-async헤더를 보낸 Image Generations 요청이 여기에 해당합니다.
비동기 호출에서 HTTP 200 응답은 게이트웨이가 요청을 접수했다는 뜻입니다. 생성이 끝났는지, 파일이 준비됐는지, 비용이 확정됐는지는 작업을 조회해 따로 확인합니다. 영상 결과는 작업 조회 결과에서 파일을 확인한 뒤 다운로드 링크를 발급받고, 이미지 결과는 작업 조회 응답의 URL로 받습니다. 영상 작업과 이미지 작업의 상태를 조회하고 결과 파일을 받는 순서는 생성 요청하고 결과 파일 받기에 있습니다.
AI 게이트웨이에서는 여러 공급사의 영상 모델을 같은 API로 호출합니다. 접수 응답의 id에서 작업 ID를 읽는 방법, 작업 상태를 조회하고 결과 파일을 받는 방법, store_media로 결과 보관 방식을 고르는 방법과 작업 비용을 확인하는 방법은 모든 영상 모델에서 같습니다.
동기 호출이든 비동기 호출이든, 같은 생성 요청을 다시 보내면 별도 호출이나 별도 작업으로 처리되어 비용이 추가로 들 수 있습니다. 다시 보내도 되는지는 오류와 재시도에서 요청 단계별로 판단합니다.
다음 단계
엔드포인트와 모델을 정했다면 모델 가이드를 보고 요청 본문을 작성하세요. 작업 ID를 반환하는 모델이라면 작업 ID로 결과를 받는 순서도 이어서 확인하세요.