API · Dleex

자체 웹사이트, 쇼핑몰 또는 스크립트에서 서비스를 주문할 수 있습니다. 서비스와 가격 목록을 조회하고, 작업 내용을 담아 주문하고, 진행 상황을 추적하고, 결과를 받아 보세요. 사이트와 동일한 서비스이므로 API로 접수한 주문은 내 계정에도 표시됩니다.

시작하기

로그인한 뒤 잔액 및 API 키 페이지를 엽니다.
키를 생성합니다. 키는 한 번만 표시되므로 복사해 두고 비밀번호처럼 안전하게 보관하세요. 키는 언제든지 폐기할 수 있습니다.
잔액을 충전합니다. API로 접수한 주문은 잔액에서 미국 달러로 결제됩니다.

모든 요청에 키를 함께 보내세요.

Authorization: Bearer dlx_your_key

API 주소: https://dleex.com/api/v1. 요청과 응답은 JSON 형식입니다. 가격과 금액은 정수 미국 센트 단위입니다. 1500은 $15.00를 뜻합니다.

서비스

GET /services는 주문할 수 있는 서비스 목록을 반환합니다.

curl https://dleex.com/api/v1/services -H "Authorization: Bearer dlx_your_key"

[
  {
    "service": "seo-article",
    "category": "seo",
    "title": { "en": "SEO article", "ru": "SEO-статья" },
    "linkRequired": false,
    "files": null,
    "script": null,
    "briefQuestions": [
      { "q": { "en": "What is the article about?", "ru": "О чём статья?" }, "hint": { "en": "The topic, or a link to the page.", "ru": "..." } },
      { "q": { "en": "Who will read it?", "ru": "..." } }
    ],
    "packages": [
      { "tier": "basic", "title": { "en": "...", "ru": "..." }, "priceUsdCents": 1500, "days": 2, "revisions": 1 },
      { "tier": "standard", "...": "..." },
      { "tier": "premium", "...": "..." }
    ],
    "addons": [
      {
        "id": 7,
        "title": { "en": "Express delivery", "ru": "Срочное выполнение" },
        "description": null,
        "priceUsdCents": 1000,
        "extraDays": -1,
        "tiers": ["standard", "premium"]
      }
    ]
  }
]

days는 작업에 걸리는 기간이고, revisions는 수정을 요청할 수 있는 횟수입니다. addons는 tiers에 나열된 패키지와 함께 주문할 수 있는 추가 옵션입니다. 가격은 패키지 가격에 더해지고, extraDays는 작업 기간에 더해집니다(음수이면 더 빨라지며, 1일 미만으로는 줄어들지 않습니다). briefQuestions는 서비스가 작업에 대해 묻는 질문이며, 일부에는 hint가 있습니다. 주문할 때 answers에 답변을 보내세요. 서비스에 질문이 없으면 목록은 비어 있습니다. linkRequired는 프로필이나 게시물, 자막을 넣을 녹음처럼 링크로 열리는 대상을 바탕으로 작업하는 서비스에서 true입니다. 이런 서비스를 주문하려면 link가 필요합니다.

files는 요청 사항과 함께 파일을 받지 않는 서비스에서 null입니다. 그 밖의 경우에는 받는 파일을 알려 줍니다. 예: {"accept": ["image"], "maxFiles": 3, "maxMb": 5, "required": true, "insteadOfLink": false}. 각각 파일 종류(image, audio, video), 요청 사항 또는 수정 요청 하나에 첨부할 수 있는 파일 수, 파일당 최대 크기(MB), 요청 사항에 파일이 하나 이상 필요한지, 파일이 link를 대신할 수 있는지를 나타냅니다(이 경우에도 파일 없이 보내는 주문에서는 linkRequired가 true입니다). 파일 섹션을 참고하세요.

script는 텍스트를 읽어 주지 않는 서비스에서 null입니다. 내레이션 서비스에는 패키지별로 읽을 수 있는 최대 텍스트 길이(문자 수)가 있습니다. 예: {"maxChars": {"basic": 1000, "standard": 3000, "premium": 9000}}. 이 서비스를 주문할 때는 글자 그대로 읽을 텍스트를 script에 보내야 합니다. 녹음은 합성 음성으로 읽습니다. 녹음을 어디에 게시하든 청취자에게 합성 음성임을 알려 주세요(이용약관 참고).

잔액

GET /balance

{ "balanceUsdCents": 10000, "currency": "USD" }

주문하기

POST /orders. 가격(패키지와 추가 옵션 합계에서 할인 차감)이 잔액에서 차감되고 작업이 즉시 시작됩니다.

필드
`service`	필수	`/services`의 서비스
`tier`	필수	`basic`, `standard` 또는 `premium`
`text`	`answers`, `script`, `awaitBrief`가 없으면 필수	작업 내용: 무엇을 해야 하는지, 최대 10,000자. `script`와 함께 보낼 때는 읽는 방식(어조, 속도, 이름 발음)
`link`	선택	페이지, 프로필, 게시물 또는 녹음 링크: 파일 직접 링크나 Dropbox 또는 Yandex Disk 링크. `linkRequired`가 `true`인 경우 필수
`answers`	선택	서비스의 `briefQuestions`에 대한 답변: `[{"q": "question", "a": "answer"}]`, 최대 8개, 답변당 최대 5,000자
`script`	`/services`의 `script`가 `null`이 아니면 필수, 그 밖에는 거부됨	글자 그대로 읽을 텍스트. 패키지의 `maxChars`까지(최대 20,000자, 줄바꿈은 1자로 계산). 문단 사이에는 빈 줄을 넣으세요
`locale`	선택	결과물의 언어, `en` 또는 `ru`. 기본값은 계정 언어
`addons`	선택	`/services`에서 이 티어에 제공되는 추가 옵션 ID. 예: `[7]`
`promoCode`	선택	프로모션 코드. 적용되지 않으면 주문이 접수되지 않습니다(오류 참고)
`awaitBrief`	선택	파일을 업로드한 뒤 요청 사항을 나중에 보내려면 `true`. 주문은 결제된 뒤 `awaiting_brief` 상태로 대기합니다. 이때는 `text`, `link`, `answers`, `script`를 생략하세요. 파일 섹션 참고

curl https://dleex.com/api/v1/orders -H "Authorization: Bearer dlx_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <your-order-id>" \
  -d '{"service":"seo-article","tier":"basic","text":"An article about trail running shoes, 5 keywords: ..."}'

Idempotency-Key는 선택 사항이며, 요청을 안전하게 반복할 수 있게 해 줍니다. 새 주문마다 새 키가 필요합니다. 아래 멱등성 섹션을 참고하세요.

text나 답변 하나 이상 중 적어도 하나를 보내거나 둘 다 보내세요. 내레이션은 script만으로 충분합니다. q에는 각 질문을 주문 언어로 briefQuestions에 있는 그대로 적고, 답변이 없는 질문은 생략하세요.

{
  "service": "seo-article",
  "tier": "basic",
  "answers": [
    { "q": "What is the article about?", "a": "Choosing trail running shoes" },
    { "q": "Who will read it?", "a": "Runners moving from road to trail" }
  ]
}

응답은 주문입니다(상태 201).

{
  "id": 1042,
  "status": "in_progress",
  "service": "seo-article",
  "tier": "basic",
  "priceUsdCents": 1500,
  "addons": [],
  "discountUsdCents": 0,
  "promoCode": null,
  "locale": "en",
  "text": "An article about trail running shoes...",
  "link": null,
  "answers": [],
  "script": null,
  "fileIds": [],
  "files": [],
  "revisionsLeft": 1,
  "createdAt": "2026-10-16T11:00:00.000Z",
  "dueAt": "2026-10-18T11:00:00.000Z",
  "deliveredAt": null,
  "autoAcceptAt": null,
  "completedAt": null,
  "results": []
}

파일

일부 서비스는 입력할 페이지 사진이나 자막을 넣을 녹음처럼 고객의 파일을 바탕으로 작업합니다. 이런 서비스는 /services의 files가 null이 아닙니다. 파일은 요청 사항을 기다리는 주문에 업로드합니다.

"awaitBrief": true를 넣고 text, link, answers, script 없이 주문합니다. 주문은 즉시 결제되고 상태는 awaiting_brief가 됩니다. 작업 기간은 요청 사항을 보낸 시점부터 시작됩니다.
파일마다 {"name": "page-1.png", "size": 482113, "mime": "image/png"}를 담아 POST /orders/{id}/files를 보냅니다. size는 바이트 단위의 정확한 크기이고 mime은 선택 사항입니다. 응답(201)은 파일 정보와 업로드할 위치입니다.

{
  "file": { "id": 77, "name": "page-1.png", "mime": "application/octet-stream", "size": 482113, "status": "pending", "used": false, "uploadExpiresAt": "2026-10-16T12:00:00.000Z", "createdAt": "2026-10-16T11:00:00.000Z" },
  "upload": { "url": "https://...", "headers": { "content-type": "application/octet-stream" }, "expiresAt": "2026-10-16T12:00:00.000Z" }
}

upload.expiresAt(1시간) 전에 파일의 바이트를 upload.url로 PUT합니다. 주어진 headers를 그대로 사용하고 API 키는 보내지 마세요.

curl -X PUT "$url" -H "content-type: application/octet-stream" --data-binary @page-1.png

POST /orders/{id}/files/{fileId}/complete. 크기가 size와 다르거나 바이트가 accept에 있는 종류가 아닌 파일은 422로 거부되고 삭제됩니다. 파일 이름과 mime은 판단에 사용되지 않습니다. 그 밖의 경우 응답은 checking 상태가 된 파일입니다. 몇 초 뒤(긴 녹음은 몇 분 뒤) ready가 되거나, reason에 사유(예: recording_no_sound, file_unreadable)와 함께 rejected가 됩니다. 파일 상태는 주문의 files에서 확인할 수 있습니다.
POST /orders와 같은 방식으로 text, link, answers, script를 담아 POST /orders/{id}/brief를 보냅니다. 아직 보내지 않은 준비된 파일이 함께 전송되며, 보낼 파일을 fileIds에 지정할 수도 있습니다. 그중 하나라도 아직 checking 상태이면 요청 사항은 409 files_not_ready로 거부됩니다. 잠시 후 다시 보내세요. 응답(200)은 in_progress 상태가 된 주문입니다.

DELETE /orders/{id}/files/{fileId}는 아직 보내지 않은 파일을 회수합니다. 주문 하나에는 최대 5개, 합계 4 GB까지 파일을 첨부할 수 있습니다. 업로드를 시작한 파일은 완료하거나 회수할 때까지 한도에 포함됩니다. 또한 업로드 시작 후 하루 동안은 회수되거나 거부된 파일도 주문의 파일과 합산해 12 GB 한도에 포함됩니다. 이를 넘으면 업로드가 409 upload_quota와 다시 받을 수 있는 시각인 retryAt와 함께 거부됩니다. 납품된 주문은 수정 요청용 파일도 받습니다. 같은 방식으로 업로드한 뒤 요청과 함께 fileIds를 보내세요.

awaitBrief 없이 보내면 파일이 required인 서비스의 주문은 400 files_required로 거부되고, 파일이 링크를 대신할 수 있는 서비스에서 링크 없이 보낸 주문은 400 link_required로 거부됩니다.

주문의 files에는 내 파일이 status와 함께 나열되고, fileIds에는 요청 사항과 함께 전송된 파일이 표시됩니다. 준비된 파일에는 결과 파일처럼 expiresAt까지 유효한 url이 있습니다. 파일은 주문이 종료된 후 30일 동안 보관됩니다.

멱등성

주문이 이미 접수된 뒤에 요청이 타임아웃될 수 있습니다. 이중 결제 없이 POST /orders를 반복하려면 Idempotency-Key 헤더를 함께 보내세요. 키는 출력 가능한 ASCII 문자 1~255자로 된 문자열이며, UUID나 자체 주문 번호처럼 주문마다 한 번 정합니다. 요청을 반복할 때는 같은 키와 같은 본문을 보내세요.

curl -i https://dleex.com/api/v1/orders -H "Authorization: Bearer dlx_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-order-981" \
  -d '{"service":"seo-article","tier":"basic","text":"An article about trail running shoes, 5 keywords: ..."}'

이 키로 이미 접수된 주문이 있으면 응답은 해당 주문의 현재 상태이며, 상태 201과 헤더 하나가 추가됩니다. 다시 결제되지 않습니다.

HTTP/1.1 201 Created
Idempotent-Replayed: true

키는 처음 함께 보낸 요청에 귀속됩니다. 같은 키를 다른 추가 옵션이나 다른 프로모션 코드처럼 다른 본문과 함께 보내면 422 idempotency_key_reused로 거부되며, 결제되지 않습니다.
같은 키로 여러 요청이 동시에 도착하면 주문은 하나만 접수되고 나머지 요청은 그 주문으로 응답합니다. 너무 오래 기다려야 하는 요청은 409 idempotency_key_in_progress로 응답하며 결제되지 않습니다. 잠시 후 다시 시도하세요.
예를 들어 400, 402, 404 또는 추가 옵션이나 프로모션 코드 오류로 실패한 요청은 키를 소진하지 않습니다. 문제를 수정한 뒤 같은 키로 다시 보내세요.
키는 24시간 동안 보관됩니다. 그 이후에는 같은 키로 새 주문이 접수됩니다.
키는 계정별로 구분됩니다. 헤더가 없으면 요청할 때마다 새 주문이 접수됩니다.

작업 승인, 요청 사항, 수정 요청에는 키가 필요하지 않습니다. 작업 승인은 반복해도 안전합니다. 주문이 완료된 후 반복하면 409 order_not_delivered로 응답합니다. 요청 사항도 마찬가지입니다. 전송이 완료된 후 반복하면 409 brief_not_expected로 응답하며 주문은 in_progress 상태입니다. 수정 요청은 다릅니다. 작업을 다시 하는 동안 반복하면 409 order_not_delivered로 응답하지만, 수정본이 납품된 후 반복하면 수정을 한 번 더 요청하게 됩니다. 수정 요청을 반복하기 전에 GET /orders/{id} (status 및 revisionsLeft)로 주문을 확인하세요.

주문 추적

GET /orders/{id}는 주문 하나를, GET /orders는 내 주문을 최신순으로 반환합니다. 목록에는 status, limit(1~100, 기본값 20), before(이전 주문을 가져올 주문 ID)를 지정할 수 있습니다.

주문 상태:

상태	의미
`awaiting_brief`	`awaitBrief`로 접수됨: `POST /orders/{id}/brief`를 기다리는 중
`in_progress`	작업 진행 중
`quality_check`	작업이 끝나 납품 전 검수 중
`delivered`	결과물 준비 완료, `results` 참고. `autoAcceptAt`까지 작업을 승인하거나 수정을 요청하세요
`revision`	요청한 수정 사항 반영 중
`completed`	결과물을 승인했거나 자동으로 승인됨
`refunded`	금액이 잔액으로 환불됨

몇 분마다 확인하면 충분하며, 더 자주 조회할 필요는 없습니다. 주문이 delivered 상태가 되면 results에 작업 결과가 담깁니다. kind는 text(Markdown), report(소셜 미디어 주문의 납품 보고서) 또는 files(다운로드할 파일, body에 선택적 메모 포함)입니다. 각 결과에는 files 목록이 있으며 텍스트와 보고서에서는 비어 있습니다. 모든 파일에는 name, mime, 바이트 단위의 size, 그리고 expiresAt까지(약 1시간) 유효한 url이 있습니다. 새 링크가 필요하면 주문을 다시 조회하세요. 링크가 파일 저장소로 리디렉션될 수 있으므로 리디렉션을 따라가도록 설정하고(예: curl -L -o result.png "$url"), API 키는 보내지 마세요. 링크만으로 파일이 열립니다.

작업 승인 및 수정

POST /orders/{id}/accept는 결과물을 승인하고 주문을 완료합니다.
{"text": "what to change"}를 담은 POST /orders/{id}/revision은 revisionsLeft가 0보다 클 때 수정을 요청합니다. 서비스가 파일을 받는 경우 fileIds에 요청용으로 업로드한 파일을 나열합니다. 생략하면 아직 보내지 않은 준비된 파일이 함께 전송됩니다.

납품된 주문을 승인하지도 수정 요청하지도 않으면 납품 3일 후 autoAcceptAt에 표시된 시각에 자동으로 승인됩니다(다른 상태에서는 null). 수정 후 다시 납품되면 3일이 새로 시작됩니다. 사이트에서도 작업을 승인할 수 있습니다. 납품 후 사이트의 주문 채팅에 메시지를 남기면 주문은 자동으로 승인되지 않으며, 작업을 승인하거나 저희가 작업을 다시 하거나 환불할 때까지 autoAcceptAt은 null입니다. 메시지에 답변한 뒤 3일을 다시 시작할 수도 있으며, 이때 autoAcceptAt에 새 시각이 표시됩니다.

오류

오류는 HTTP 상태와 코드로 반환됩니다.

{ "code": "insufficient_balance" }

상태	코드	의미
400	`validation`	필드가 없거나 잘못되었습니다. `fields`에 해당 필드가 나열됩니다
400	`link_required`	이 서비스에는 `link`가 필요합니다
400	`files_required`	이 서비스에는 파일이 필요합니다. `awaitBrief`로 주문한 뒤 파일을 업로드하세요
400	`script_required`	이 서비스는 텍스트를 읽어 줍니다. `script`에 텍스트를 보내세요
400	`script_too_long`	`script`가 패키지에서 읽을 수 있는 길이보다 깁니다. 응답의 `maxChars`가 최대 길이입니다. 결제되지 않았습니다
400	`script_not_accepted`	텍스트를 읽어 주지 않는 서비스입니다(`/services`의 `script`가 `null`). `script`를 생략하세요. 결제되지 않았습니다
400	`files_not_accepted`, `file_too_large`	파일을 받지 않는 서비스이거나 파일이 `maxMb`보다 큽니다
400	`invalid_idempotency_key`	`Idempotency-Key`가 비어 있거나, 255자를 넘거나, 출력 가능한 ASCII가 아닙니다
401	`invalid_api_key`	키가 없거나, 잘못되었거나, 폐기되었습니다. 계정의 미인증 이메일이 Google 로그인이나 새 비밀번호 설정으로 인증되면 키도 폐기됩니다
402	`insufficient_balance`	잔액이 부족합니다. 결제되지 않았습니다
404	`package_not_found`, `order_not_found`, `file_not_found`	해당 서비스, 패키지, 주문 또는 파일이 없습니다
409	`order_not_delivered`, `no_revisions_left`	주문이 이 작업을 할 수 있는 상태가 아닙니다
409	`brief_not_expected`	주문이 요청 사항을 기다리고 있지 않습니다. `awaitBrief` 없이 접수되었거나 요청 사항이 이미 전송되었습니다
409	`uploads_closed`	파일은 주문이 요청 사항을 기다리거나 납품된 상태일 때만 받습니다
409	`files_limit`	서비스가 요청 사항 또는 요청 하나에 받는 수보다 파일이 많거나, 주문의 파일이 5개 또는 4 GB를 넘습니다
409	`upload_quota`	이 파일을 포함해 주문의 파일(전송된 파일과 완료되지 않은 업로드 포함)과 최근 하루 동안 업로드를 시작한 뒤 회수되거나 거부된 파일이 12 GB를 넘습니다. `retryAt` 이후에 다시 시도하세요
409	`files_not_ready`, `file_rejected`	보낼 파일이 아직 검사 중이거나 거부되었습니다
409	`upload_incomplete`	아직 링크에 업로드된 내용이 없습니다. `PUT`을 마친 뒤 업로드를 다시 완료하세요
409	`file_in_use`, `file_busy`	파일이 요청 사항이나 요청과 함께 전송되어 주문에 남아 있거나, 검사 과정에서 이동 중입니다. 잠시 후 다시 시도하세요
409	`addon_unavailable`	이 서비스와 티어에서 제공되지 않는 추가 옵션입니다
409	`promo_not_found`, `promo_inactive`, `promo_used_up`, `promo_already_used`, `promo_first_order_only`, `promo_min_order`	프로모션 코드가 존재하지 않거나, 현재 활성 상태가 아니거나, 모두 소진되었거나, 이미 사용했거나, 첫 주문 전용이거나, 더 큰 금액의 주문이 필요합니다. 결제되지 않았습니다
409	`idempotency_key_in_progress`	이 `Idempotency-Key`의 요청이 아직 처리 중입니다. 잠시 후 다시 시도하세요
410	`upload_expired`, `file_removed`	업로드되기 전에 업로드 링크가 만료되었거나 파일을 회수했습니다. 새 업로드를 시작하세요
415	`file_type_not_accepted`	지정한 `mime`이 서비스가 받는 종류가 아닙니다
422	`idempotency_key_reused`	이 `Idempotency-Key`는 이미 다른 요청에 사용되었습니다
422	`upload_size_mismatch`, `file_type_not_accepted`	업로드한 파일의 길이가 `size`와 다르거나, 바이트가 서비스가 받는 종류가 아닙니다. 파일은 삭제되었습니다
422	`file_unreadable`, `recording_no_sound`, `check_failed`	검사에서 거부된 파일을 완료하려 했습니다. 파일이 열리지 않거나, 녹음에 소리가 없거나, 검사할 수 없었습니다. 파일을 다시 업로드하거나 다른 파일을 업로드하세요
429	`rate_limited`	키 하나로 분당 120회를 넘는 요청을 보냈습니다. `Retry-After`에 표시된 초만큼 기다리세요

환불

주문이 환불되면 금액이 잔액으로 돌아가고 주문은 refunded 상태가 됩니다.