API 문서
API 문서
API 키로 모든 AI 기능을 호출, 종량제 과금, 몇 줄의 코드로 연동.
인증
모든 API 요청에 Authorization 헤더를 포함해야 합니다.
Authorization: Bearer sk-xxxxxxxxxxxxxxxxAPI 키는 콘솔의 "API 키" 페이지에서 발급받을 수 있습니다. 계정당 하나의 키입니다. 재설정은 콘솔에서 가능하며, 재설정 후 기존 키는 즉시 무효화됩니다.
작업 생성
POST
https://nsfwrouter.xyz/api/v1/tasks/create
AI 작업을 GPU 클러스터에 제출하여 실행합니다. 작업은 비동기 처리되며, 작업 ID가 반환됩니다. 조회 API 또는 Webhook으로 결과를 확인하세요.
요청 파라미터
| 파라미터 | 유형 | 필수 | 설명 |
|---|---|---|---|
| tool_id | int | 예 | 도구 ID, 도구 목록에서 확인 |
| params | object | 예 | 작업 파라미터, JSON 객체, 필드는 도구에 따라 다름 |
| webhook_url | string | 아니오 | 작업 완료 후 콜백 알림 URL |
| priority | int | 아니오 | 작업 우선순위 1-10, 기본값 5 |
| idempotency_key | string | 아니오 | 멱등성 키, 중복 제출 방지 |
| execution_options | object | 아니오 | 실행 옵션, JSON 객체 |
요청 예시
curl -X POST https://nsfwrouter.xyz/api/v1/tasks/create \
-H "Authorization: Bearer sk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"tool_id": 1,
"params": {
"image": "https://example.com/photo.jpg",
"prompt": "a beautiful landscape"
},
"webhook_url": "https://your-server.com/webhook"
}'응답 예시
{
"code": 0,
"message": "success",
"data": {
"task": {
"id": 123,
"status": 0,
"consume_coins": 5
},
"message": "task_submitted"
}
}호출 전 계정 잔액을 검증합니다. 잔액 부족 시 insufficient_coins 오류를 반환합니다. 작업 제출 성공 후 코인이 즉시 차감됩니다.
작업 상세 조회
GET
https://nsfwrouter.xyz/api/v1/tasks/query
작업 ID로 작업 상세와 상태를 조회합니다. 작업 처리 중에는 GPU 클러스터의 최신 상태를 동기화하여 가져옵니다. 10초 이내 중복 조회는 데이터베이스 캐시 결과를 반환하며, 원격 요청을 반복하지 않습니다.
조회 파라미터
| 파라미터 | 유형 | 필수 | 설명 |
|---|---|---|---|
| id | int | 예 | 작업 ID |
응답 예시
{
"code": 0,
"message": "success",
"data": {
"task": {
"id": 123,
"status": 1,
"task_output_json": [
{
"type": "image",
"url": "https://cdn.example.com/outputs/abc123.png",
"file_name": "abc123.png",
"file_size": 1024000,
"mime_type": "image/png",
"width": 1024,
"height": 1024
}
],
"consume_coins": 5,
"created_at": 1718200000,
"completed_at": 1718200015
}
}
}작업 상태 값
| status | 의미 |
|---|---|
| 0 | 처리 중 |
| 1 | 완료 |
| -1 | 취소 |
| -2 | 실패 |
작업 목록
GET
https://nsfwrouter.xyz/api/v1/tasks
현재 계정의 작업 목록을 페이지네이션으로 조회, 도구, 상태, 시간 범위로 필터링 가능.
조회 파라미터
| 파라미터 | 유형 | 필수 | 설명 |
|---|---|---|---|
| page | int | 아니오 | 페이지 번호, 기본값 1 |
| page_size | int | 아니오 | 페이지 크기, 기본값 20, 최대 50 |
| tool_id | int | 아니오 | 도구별 필터 |
| status | int | 아니오 | 상태별 필터 (0/1/-1/-2) |
| days | int | 아니오 | 조회 기간(일), 기본값 30 |
응답 예시
{
"code": 0,
"message": "success",
"data": {
"list": [
{
"id": 123,
"tool_id": 1,
"status": 1,
"task_output_json": [
{
"type": "image",
"url": "https://cdn.example.com/outputs/abc123.png",
"file_name": "abc123.png",
"file_size": 1024000,
"mime_type": "image/png",
"width": 1024,
"height": 1024
}
],
"error": null,
"consume_coins": 5,
"created_at": 1718200000,
"completed_at": 1718200015
},
{
"id": 122,
"tool_id": 3,
"status": 0,
"task_output_json": [],
"error": null,
"consume_coins": 10,
"created_at": 1718199000,
"completed_at": 0
}
],
"page": 1,
"page_size": 20
}
}task_output_json item 필드 설명
| 필드 | 유형 | 설명 |
|---|---|---|
| type | string | 결과 유형: image 또는 video |
| url | string | 결과 파일 CDN URL |
| file_name | string | 파일명 |
| file_size | int | 파일 크기(바이트) |
| mime_type | string | MIME 유형, 예: image/png, video/mp4 |
| width | int | 너비(픽셀) |
| height | int | 높이(픽셀) |
계정 잔액
GET
https://nsfwrouter.xyz/api/v1/account/balance
현재 계정의 코인 잔액, 총 충전액, 총 소비액을 조회합니다.
응답 예시
{
"code": 0,
"message": "success",
"data": {
"remain_coins": 5000,
"total_coins": 10000,
"used_coins": 5000
}
}Webhook 콜백
작업 생성 시 webhook_url을 지정하면, 작업 완료, 실패 또는 취소 시 해당 URL로 POST 요청이 전송됩니다. 요청 본문은 JSON 형식입니다.
콜백 요청 헤더
Content-Type: application/json
Accept: application/json
User-Agent: OpenAPI-Webhook/1.0콜백 요청 본문
{
"event": "task.finished",
"task": {
"id": 123,
"status": 1,
"task_output_json": [
{
"type": "image",
"url": "https://cdn.example.com/outputs/abc123.png",
"file_name": "abc123.png",
"file_size": 1024000,
"mime_type": "image/png",
"width": 1024,
"height": 1024
}
],
"consume_coins": 5,
"created_at": 1718200000,
"completed_at": 1718200015
}
}서버는 수신 성공을 나타내는 HTTP 2xx 상태 코드를 반환해야 합니다. 비-2xx 응답이나 타임아웃(10초) 발생 시, 시스템은 자동으로 최대 5회까지 지수 백오프 전략(60s → 120s → 240s → 480s → 960s)으로 재시도합니다.
오류 코드
모든 오류 응답은 통일된 형식: {"code": 오류코드, "message": "오류식별자", "data": {}}
| 오류 코드 | message | 설명 |
|---|---|---|
| 20001 | api_key_required | API 키가 제공되지 않았습니다 |
| 20001 | invalid_api_key | 유효하지 않은 API 키 |
| 20001 | ip_not_allowed | IP가 화이트리스트에 없습니다 |
| 20001 | permission_denied | 접근 권한이 없습니다 |
| 30001 | tool_not_found | 도구를 찾을 수 없습니다 |
| 30001 | task_not_found | 작업을 찾을 수 없습니다 |
| 30001 | insufficient_coins | 코인 잔액 부족 |
| 30001 | task_submit_failed | 작업 제출 실패 |
| 30001 | task_query_failed | 작업 조회 실패 |
| 30001 | task_already_exists | 작업이 이미 존재합니다 (멱등성 적중) |
| 40001 | tool_id_required | tool_id 파라미터 누락 |
| 40001 | param_error | 파라미터 오류 |
| 40001 | webhook_url_invalid | webhook_url 형식이 올바르지 않습니다 |
| 40001 | params_must_be_json_object_or_array | params는 JSON 객체 또는 배열이어야 합니다 |
| 40001 | execution_options_must_be_json_object_or_array | execution_options는 JSON 객체 또는 배열이어야 합니다 |
오류 코드 범위
| 범위 | 카테고리 |
|---|---|
| 1xxxx | 시스템 오류 |
| 2xxxx | 인증 오류 |
| 3xxxx | 비즈니스 로직 오류 |
| 4xxxx | 파라미터 오류 |
| 5xxxx | 외부 의존성 오류 |