LogoJoyAI Image

JoyAI Image API

API 문서

하나의 공개 API로 이미지를 생성하고 편집하세요. joyai 는 지시 기반 편집, gptimage2 는 GPT Image 2 텍스트-이미지 및 편집에 사용합니다.

API 키 관리빠른 시작

개요

엔드포인트

/api/v1/generate

지원 이미지 모델용 단일 엔드포인트. model 필드로 동작 선택.

Auth

Bearer API 키

Authorization 헤더에 대시보드 API 키 사용. 서버 키는 브라우저로 전송되지 않습니다.

Async

태스크 기반 결과

생성은 task ID를 반환합니다. status를 폴링해 최종 URL을 받으세요.

인증

모든 요청에는 Authorization 헤더의 API 키가 필요합니다. 키 생성/교체: 대시보드 > API 키.

헤더
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

모델 및 크레딧

model적합 용도이미지 입력 필요크레딧
joyai참조 이미지 1~3장으로 지시 기반 편집.예, 이미지 URL 1~3개.요청당 24 크레딧.
gptimage2GPT Image 2 텍스트-이미지 및 편집.선택. 이미지 추가 시 편집 모드.Text: 1k/2k/4k low 2/4/6, medium 12/24/36, high 44/88/132. Edit: low 6/12/18, medium 12/24/36, high 44/88/132.

빠른 시작

다음으로 요청을 보냅니다: POST /api/v1/generate. 에 요청을 보냅니다. API는 즉시 task ID를 반환하며, GET /api/v1/status 로 성공 또는 실패까지 폴링하세요.

cURL
curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A premium product photo of a matte black espresso machine on a marble counter",
    "quality": "medium",
    "resolution": "1k",
    "aspect_ratio": "1:1"
  }'

POST /api/v1/generate

이미지 생성 또는 편집 태스크를 생성합니다. 요청 본문은 JSON입니다.

요청 매개변수

이름유형필수설명
modelstring예joyai 또는 gptimage2 사용.
promptstring예자연어 지시. joyai 최대 1500자, gptimage2 최대 20000자.
imagesstring[]joyai 필수, gptimage2 선택이미지 URL. joyai 1~3개, gptimage2는 이미지 있으면 편집 모드.
sizestringjoyai 선택1024*1024 등. 기본 1024*1024.
qualitystringgptimage2 선택low, medium, high. 기본 medium.
resolutionstringgptimage2 선택1k, 2k, 4k. 기본 1k.
aspect_ratiostringgptimage2 선택1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.
output_formatstringgptimage2 선택png, jpeg, webp. 기본 png.
callback_urlstring선택태스크와 함께 저장 가능한 콜백 URL.

JoyAI 편집 예시

cURL
curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "joyai",
    "prompt": "Replace the mug logo with clean white text that says JOYAI while preserving reflections and shadows.",
    "images": ["https://example.com/source-product.jpg"],
    "size": "1024*1024"
  }'

GPT Image 2 예시

cURL
curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A cinematic studio portrait of a red ceramic chair, softbox lighting, neutral backdrop",
    "quality": "high",
    "resolution": "2k",
    "aspect_ratio": "4:5",
    "output_format": "png"
  }'

응답

JSON
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "processing",
    "credits_charged": 88
  }
}

GET /api/v1/status

다음이 반환한 task ID로 상태를 폴링합니다: /api/v1/generate. 가 반환한 task ID로 상태를 폴링합니다. model은 선택이며 가능하면 자동 라우팅됩니다.

cURL
curl "https://joyai-image.com/api/v1/status?task_id=task_id_here" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "succeeded",
    "credits_charged": 88,
    "images": ["https://cdn.example.com/result.png"],
    "error": null,
    "created_at": "2026-06-06 12:00:00"
  }
}

오류

오류는 성공 응답과 동일한 형식입니다. 공개 응답에 내부 공급자명이나 라우팅 세부사항은 노출되지 않습니다.

JSON
{
  "code": 400,
  "message": "prompt is required",
  "data": null
}
상태의미
400매개변수 누락 또는 잘못됨.
401API 키 누락 또는 잘못됨.
402크레딧 부족.
500생성 서비스 또는 서버 오류. 반복 시 지원팀에 문의.