요청

요청은 하나의 모델을 한 번 호출하는 것입니다. 요청에는 id(req_…), 상태, API 크레딧 기준 비용(1000 = 1 USD)이 있으며, 요청이 성공하면 생성된 파일도 포함됩니다. 아래의 모든 엔드포인트에서 모든 모델에 대해 동일한 객체가 반환됩니다.

모델 찾기#

1,496개 모델의 전체 카탈로그는 공개 JSON입니다(API 키 불필요).

curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"

각 행에는 id, name, lab, category, family, summary, tags, output_kind, docs_url 및 price 객체가 있습니다(가격 책정 참조). GET https://api.doitong.com/v1/models/{model_id}를 사용하면 전체 입력 및 출력 JSON Schema, 표준 매개변수 이름, 가격 규칙 및 예시 입력이 추가로 반환됩니다. 알 수 없는 category 또는 mode는 400 invalid_parameter를 반환합니다.

모델 실행#

curl -X POST "https://api.doitong.com/v1/run/{model_id}?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-cover" \
  -d '{"prompt": "..."}'

• 본문은 JSON 객체 형식의 모델 입력입니다. 각 모델 페이지에 매개변수가 나와 있습니다.
• 입력은 비용이 청구되기 전에 확인됩니다. 잘못된 입력은 문제가 있는 param과 함께 422 invalid_input을 반환하며 비용이 청구되지 않습니다.
• ?wait=N(최대 20초)은 요청이 완료되거나 시간이 만료될 때까지 호출을 유지합니다.
• ?webhook_url=https://…은 요청이 완료되면 해당 URL로 서명된 POST를 전송합니다(웹훅 참조).
• ?storage=permanent 또는 ?storage=temporary는 출력 파일을 얼마나 오래 보관할지 지정합니다. 지정하지 않으면 계정 설정이 적용됩니다(파일 보관 위치 참조).

요청이 아직 처리 중이면 응답은 202 Accepted이고, 대기 시간 내에 완료되면 200 OK입니다(또는 아래 설명하는 재생 요청인 경우). Location 및 Doitong-Request-Id 헤더에 요청 URL과 id가 들어 있습니다.

상태#

시간 제한보다 오래 실행된 요청은 timeout 코드로 실패하고 환불됩니다. 이미지에는 15분, 동영상에는 60분, 오디오 및 기타 항목에는 30분이 적용됩니다.

요청 객체#

{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:01Z",
  "completed_at": "2026-10-20T12:00:02Z",
  "queue_position": null,
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "input": { "prompt": "..." },
  "output": { "images": [ { "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "width": 1024, "height": 768 } ] },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "content_type": "image/jpeg",
      "width": 1024, "height": 768, "file_size": 183920, "stored": true }
  ],
  "error": null,
  "metrics": { "inference_seconds": 1.2 },
  "storage": { "mode": "permanent", "bytes": 183920, "expires_at": null, "expired": false },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}

• outputs는 모든 모델에서 동일합니다. 생성된 파일마다 하나의 항목이 있으며 type(image, video, audio, file 또는 3d), 스토리지의 url, content_type 및 확인 가능한 경우 file_size, width, height, duration이 포함됩니다.
• output은 모델 자체의 결과 객체입니다(필드는 각 모델 페이지에 나열됨). 동일한 URL이 포함됩니다.
• storage는 파일 보관 방식을 나타냅니다. mode(permanent 또는 temporary), 저장된 bytes, expires_at(임시 파일이 삭제되는 시점이며 영구 파일은 null) 및 expired(파일이 삭제되면 true)가 포함됩니다.
• cost.credits는 API 크레딧 기준 호출 가격이며(cost.usd는 USD 기준), cost.charged는 API 잔액에서 차감된 금액, cost.refunded는 환불된 금액입니다. metered 모델에서는 cost.credits가 시작 시 보류된 최대 금액입니다(cost.held). 실행이 성공하면 cost.settled에 실제 사용량이 표시되고 최대 금액과의 차액은 cost.refunded에 들어갑니다(사용량에 따른 청구 참조).
• 요청이 실패하면 error는 { "type": …, "code": …, "message": … } 형식입니다.

요청 조회#

curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• ?wait=N(최대 20초)은 롱 폴링을 수행합니다. 요청이 최종 상태가 되면 즉시 반환되며, 그렇지 않으면 N초 후 현재 상태를 반환합니다. 결과를 기다리는 가장 간단한 방법입니다.
• ?logs=1을 지정하면 모델 진행 로그 줄(최근 50개)이 logs로 추가됩니다.

자신의 계정에 속한 요청만 조회할 수 있습니다. 다른 id를 사용하면 404 request_not_found가 반환됩니다.

요청 목록 조회#

curl "https://api.doitong.com/v1/requests?limit=20&status=succeeded&model=flux/schnell" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

최신 항목부터 표시됩니다. limit은 1~100(기본값 20)이며, status와 model로 필터링할 수 있습니다. 응답은 { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" } 형식입니다. 다음 페이지를 가져오려면 cursor=<next_cursor>를 전달합니다.

요청 취소#

curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• 모델이 시작되기 전에 취소하면 상태가 canceled가 되고 API 크레딧이 환불되며 200이 반환됩니다.
• 이미 생성 중이면 취소 요청이 전달되고 "cancel_requested": true와 함께 202가 반환됩니다. 모델이 계속 실행되어 완료되면 요청은 정상적으로 성공하고 비용이 청구됩니다.
• 이미 최종 상태이면 409 not_cancelable입니다(이미 canceled인 요청은 200을 반환합니다).

요청의 파일 삭제#

curl -X DELETE "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

요청의 출력 파일 사본을 스토리지에서 즉시 삭제하고 스토리지 요금 청구를 중지합니다. 응답은 storage.expired: true가 포함된 요청 객체입니다. 레코드에 URL은 남지만 더 이상 작동하지 않습니다. 다시 호출해도 아무 변경이 없습니다 (200). 아직 queued 또는 running 상태인 요청에는 파일이 없으므로 409 request_active가 반환됩니다. models:run이 필요합니다.

멱등성: 이중 청구 없이 재시도#

네트워크는 실패할 수 있습니다. 안전하게 재시도하려면 Idempotency-Key 헤더를 전송합니다(최대 255자의 문자열, 작업마다 고유해야 하며, 예를 들어 자체 주문 id를 사용할 수 있음).

• 이전과 동일한 키와 동일한 본문: 원래 요청이 반환됩니다(200, 헤더 Idempotent-Replayed: true). 다시 비용이 청구되지 않습니다.
• 모델에 도달하기 전에 실패한 실행 후 동일한 키와 본문을 사용한 경우(upstream_error 또는 internal_error가 제출 시 발생하거나, insufficient_credits, budget_exceeded, too_many_inflight인 경우): 생성된 것이 없고 비용도 청구되지 않으므로 실패를 반환하는 대신 재시도 시 모델이 다시 실행됩니다.
• 동일한 키와 다른 본문: 409 idempotency_mismatch입니다.
• 키의 범위는 해당 키를 전송한 API 키로 제한됩니다.

파일 보관 위치#

모든 출력 파일은 요청이 succeeded로 표시되기 전에 스토리지에 복사되므로 outputs의 URL은 자체 호스트를 가리키며 직접 링크할 수 있습니다. 파일을 얼마나 오래 보관할지는 직접 선택합니다.

• 새 요청에는 계정 설정이 적용됩니다. 대시보드의 "파일 영구 보관" 스위치를 사용하거나 PATCH https://api.doitong.com/v1/account/storage에 {"mode": "temporary"}를 전달할 수 있습니다. GET https://api.doitong.com/v1/account의 storage에 설정과 보관 중인 바이트 및 월별 예상 금액이 표시됩니다.
• 실행 시 ?storage=permanent|temporary를 지정하면 해당 실행에 한해 설정을 덮어씁니다(MCP run 도구의 storage 인수).
• 설정을 변경해도 이미 보관 중인 파일에는 영향을 주지 않습니다. 해당 파일은 DELETE /requests/{id}/files로 삭제합니다.
• API 잔액으로 스토리지 비용을 지불할 수 없으면 비용이 청구되지 않고 이메일이 발송됩니다. 30일 이내에 충전하지 않으면 보관 중인 파일이 임시 파일로 전환되고 7일 후 삭제됩니다.

드물게 자체 사본 생성에 실패하면 항목에 "stored": false가 표시되고 URL은 원본의 짧은 유효 기간 URL이 됩니다. 즉시 다운로드하세요.