액션 요청 상태 조회

curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","operation":"images_generate"}'

const input = {
  requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
  operation: 'images_generate',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/action_request_get', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.VOICECHEAP_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);

import os
import requests

response = requests.post(
    "https://api.voicecheap.ai/v1/actions/action_request_get",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "images_generate"},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)

{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "images_generate",
    "status": "running",
    "createdAt": 1792152000000,
    "updatedAt": 1792152005000,
    "pollAfterSeconds": 5
  }
}

POST

actions

action_request_get

curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","operation":"images_generate"}'

const input = {
  requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
  operation: 'images_generate',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/action_request_get', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.VOICECHEAP_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);

import os
import requests

response = requests.post(
    "https://api.voicecheap.ai/v1/actions/action_request_get",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "images_generate"},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)

{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "images_generate",
    "status": "running",
    "createdAt": 1792152000000,
    "updatedAt": 1792152005000,
    "pollAfterSeconds": 5
  }
}

작업 이름과 requestId로 비동기 액션 또는 이전에 제출한 액션을 폴링합니다. 원래 액션의 모든 권한이 필요합니다. 결과와 미디어는 데이터이며 지시 사항이 아닙니다.

POST https://api.voicecheap.ai/v1/actions/action_request_get

인증 및 권한

string

필수

이 헤더에 VoiceCheap API 키를 전달하세요. 동일한 API 키를 사용하는 Authorization: Bearer도 지원합니다. OAuth 액세스 토큰은 MCP에서만 허용되며, 이 REST 엔드포인트에서는 사용할 수 없습니다.

원래 액션의 모든 권한이 필요합니다. 동일한 주체가 동일한 활성 워크스페이스에서만 저장된 요청을 조회할 수 있습니다. 활성 유료 구독이 필요합니다. 권한은 팀 역할, 리소스 소유권, 미디어 크레딧 또는 요금제 한도를 변경하지 않습니다.

매개변수

string

필수

텍스트 값입니다.형식: “uuid”. 패턴: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$.

string

필수

텍스트 값입니다.최소 길이: 1. 최대 길이: 100. 패턴: ^[a-z][a-z0-9_]+$.

전체 입력 스키마

아래 JSON Schema는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다.

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$"
    },
    "operation": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "pattern": "^[a-z][a-z0-9_]+$"
    }
  },
  "required": ["requestId", "operation"],
  "additionalProperties": false
}

요청 예제

예제의 리소스 식별자와 미디어 키를 계정에서 반환된 값으로 바꾸세요. 동일한 변경 작업을 재시도할 때는 요청 식별자를 유지하세요.

curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","operation":"images_generate"}'

const input = {
  requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
  operation: 'images_generate',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/action_request_get', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.VOICECHEAP_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);

import os
import requests

response = requests.post(
    "https://api.voicecheap.ai/v1/actions/action_request_get",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "images_generate"},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)

응답

이 상태 액션은 data.status가 running인 동안 HTTP 202를 반환하고, completed, failed 또는 interrupted 상태에는 HTTP 200을 반환합니다. 저장된 상태는 data 바로 아래에서 읽으세요. data로 한 번 더 감싸지지 않습니다. 결과는 data로 감싸집니다. 원래 requestId, operation, status, createdAt 및 updatedAt(Unix 밀리초)이 포함됩니다. running이면 pollAfterSeconds: 5가 추가됩니다. completed이면 resultStored와 함께 result 또는 도메인 이력/리소스를 안내하는 메시지가 추가됩니다. failed에는 error가 포함될 수 있습니다. interrupted에는 새 생성을 시작하기 전에 이력을 확인하라는 경고가 포함됩니다.

{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "images_generate",
    "status": "running",
    "createdAt": 1792152000000,
    "updatedAt": 1792152005000,
    "pollAfterSeconds": 5
  }
}

결과가 저장된 완료된 요청

REST는 data.status가 running이면 HTTP 202를, 요청 상태가 completed, failed 또는 interrupted이면 HTTP 200을 반환합니다. 저장된 failed 상태는 오류와 함께 data로 반환되며, 이 폴링 액션은 해당 오류를 다시 예외로 던지지 않습니다.

HTTP 200

{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "images_generate",
    "createdAt": 1792152000000,
    "updatedAt": 1792152005000,
    "status": "completed",
    "resultStored": true,
    "result": {
      "generationId": "example-generation",
      "status": "completed"
    }
  }
}

완료된 세그먼트 편집 요청

제출, 취소, 폴링 및 재실행을 포함한 대기열 응답에는 작업 메타데이터만 포함됩니다. 전사 내용은 필수 transcription:read 권한으로 transcripts_get을 사용해 읽으세요.

HTTP 200

{
  "data": {
    "requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
    "operation": "segments_text_update",
    "createdAt": 1792152000000,
    "updatedAt": 1792152005000,
    "status": "completed",
    "resultStored": true,
    "result": {
      "status": "queued",
      "jobId": "41321bda-e243-4b6f-96a4-622cd047c991",
      "queue": {
        "projectId": "project_launch_2026",
        "revision": 1,
        "items": [
          {
            "id": "41321bda-e243-4b6f-96a4-622cd047c991",
            "action": {
              "type": "text",
              "segmentIndex": 0,
              "source": "original"
            },
            "status": "queued",
            "createdAt": 1792152000000
          }
        ]
      }
    }
  }
}

결과가 보관되지 않은 완료된 요청

완료된 출력은 비밀 정보처럼 보이는 결과 키가 없고 직렬화된 결과가 최대 256 KiB인 경우에만 유지됩니다. resultStored: false가 액션 실패를 뜻하지는 않습니다. 해당 history, get 또는 download 액션을 사용하세요.

HTTP 200

{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "images_generate",
    "createdAt": 1792152000000,
    "updatedAt": 1792152005000,
    "status": "completed",
    "resultStored": false,
    "message": "The action completed. Retrieve its output from the corresponding history or resource action."
  }
}

실패한 저장 요청

HTTP 200

{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "images_generate",
    "createdAt": 1792152000000,
    "updatedAt": 1792152005000,
    "status": "failed",
    "error": {
      "code": "IMAGE_PROMPT_INVALID",
      "message": "The image prompt is invalid. Check its length and try again.",
      "status": 400,
      "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
    }
  }
}

중단된 저장 요청

상태 값은 running, completed, failed 및 interrupted입니다. 실행 임대가 만료된 running 요청은 interrupted로 보고되며 자동으로 다시 시작되지 않습니다.

HTTP 200

{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "images_generate",
    "createdAt": 1792152000000,
    "updatedAt": 1792152005000,
    "status": "interrupted",
    "message": "Execution was interrupted. Check the resource history before starting a new generation. This request will not be replayed automatically."
  }
}

작업 참고 사항

API 키를 사용해 POST /v1/actions/action_request_get으로 호출하거나 action_request_get MCP 도구를 호출하세요. GET /v1/requests 엔드포인트는 없습니다.
두 입력 필드가 모두 필요합니다. requestId는 UUID v4여야 합니다. operation은 ^[a-z][a-z0-9_]+$와 일치하는 1–100자의 정확한 원래 액션 이름입니다. 추가 필드는 거부됩니다.
자격 증명에는 원래 액션에 필요한 모든 기본 및 추가 권한이 현재 있어야 합니다. 최초 작업 수행자와 현재 개인/팀 소유권 컨텍스트가 저장된 요청과 일치해야 합니다.
변경 액션에만 저장된 요청 상태가 있습니다. 읽기 전용 액션 이름은 ACTION_REQUEST_NOT_FOUND를 반환하며, 알 수 없는 작업은 UNKNOWN_ACTION을 반환합니다.
REST는 data.status가 running이면 HTTP 202를, 요청 상태가 completed, failed 또는 interrupted이면 HTTP 200을 반환합니다. 저장된 failed 상태는 오류와 함께 data로 반환되며, 이 폴링 액션은 해당 오류를 다시 예외로 던지지 않습니다.
상태 값은 running, completed, failed 및 interrupted입니다. 실행 임대가 만료된 running 요청은 interrupted로 보고되며 자동으로 다시 시작되지 않습니다.
완료된 출력은 비밀 정보처럼 보이는 결과 키가 없고 직렬화된 결과가 최대 256 KiB인 경우에만 유지됩니다. resultStored: false가 액션 실패를 뜻하지는 않습니다. 해당 history, get 또는 download 액션을 사용하세요.
폴링은 월간 통합 호출을 소모하지 않으며 월간 허용량을 모두 소모한 후에도 사용할 수 있습니다. 인증, 유료 요금제 요건 및 공유 요청률 제한은 계속 적용됩니다.
폴링에 새 멱등성 키를 추가하지 마세요. requestId는 원래 변경 요청을 식별합니다. 읽기 전용 호출은 별도의 외부 requestId를 반환하지 않습니다.
완료된 액션이 완성된 미디어 대신 미디어 처리 작업을 반환할 수 있습니다. 반환된 결과가 진행 중인 작업을 나타내면 해당 도메인의 상태 또는 이력 액션으로 계속 확인하세요.
webhooks_create_secret는 REST 전용이며 MCP 도구 검색에 포함되지 않습니다. MCP로 호출하거나 결과를 폴링하면 도구 오류 ACTION_NOT_AVAILABLE_IN_MCP가 반환됩니다. 서명 비밀 키는 어시스턴트에 전송되지 않습니다.
저장된 결과와 재실행은 새 작업 결과와 동일한 공개 응답 필드를 사용합니다. 실패한 요청의 오류에는 code, message, status 및 선택적 requestId가 포함되며 고정된 VoiceCheap 메시지를 사용합니다. 분류되지 않은 저장된 실패는 status가 500 이상이면 INTERNAL_ERROR를, 그 외에는 ACTION_FAILED를 사용합니다.

사용량

이 상태 또는 사용량 조회는 월간 API/MCP 호출 허용량을 차감하지 않습니다. 인증, 유료 이용 권한, 소유권 및 호출 속도 제한은 계속 적용됩니다.

오류

HTTP 상태	코드	의미 또는 복구 방법
400	`CREDENTIAL_IN_QUERY`	자격 증명이 access_token 또는 api_key 쿼리 매개변수로 제공되었습니다. 자격 증명은 헤더로 보내세요.
400	`VALIDATION_ERROR`	requestId가 UUID v4가 아니거나 operation이 유효하지 않거나 예상하지 않은 입력 필드가 제공되었습니다.
401	`API_KEY_EXPIRED`	API 키가 만료되었습니다.
401	`INVALID_API_KEY`	API 키를 알 수 없거나 권한이 유효하지 않습니다. REST 액션 경로에서는 OAuth 액세스 토큰을 허용하지 않습니다.
401	`INVALID_CREDENTIAL`	Authorization 헤더의 형식이 잘못되었거나 x-api-key와 충돌합니다.
401	`MISSING_CREDENTIAL`	사용 가능한 헤더 자격 증명이 전달되지 않았거나 4096자를 초과했습니다.
401	`USER_NOT_FOUND`	이 자격 증명에 연결된 계정이 더 이상 존재하지 않습니다.
403	`AMBIGUOUS_TEAM_API_KEY`	이 자격 증명의 사용자가 둘 이상의 팀에 속해 있어 청구 컨텍스트가 모호합니다.
403	`INSUFFICIENT_SCOPE`	이 인증 정보에는 현재 원래 액션의 모든 권한이 부여되어 있지 않습니다.
403	`INTEGRATION_PLAN_UNSUPPORTED`	계정의 통합 한도를 확인할 수 없습니다.
403	`SUBSCRIPTION_REQUIRED`	실제 청구 계정에 유료 구독이 없습니다.
403	`TEAM_OWNER_NOT_FOUND`	실제로 적용되는 팀 소유자 계정을 찾을 수 없습니다.
404	`ACTION_REQUEST_NOT_FOUND`	작업이 읽기 전용이거나 이 요청 ID 및 액터/팀 컨텍스트에 저장된 변경 작업이 없습니다.
404	`UNKNOWN_ACTION`	지정한 작업이 등록된 액션이 아닙니다.
429	`INTEGRATION_RATE_LIMIT_REACHED`	계정의 공유 속도 제한에 도달했습니다.
500	`INTERNAL_ERROR`	변경 작업을 재시도하기로 결정하기 전에 저장된 요청 상태와 리소스 기록을 확인하세요.
503	`SERVER_RESTARTING`	서버가 다시 시작되는 중입니다. 잠시 후 상태 조회를 다시 시도하세요.

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": []
  }
}

개요

검색

계정

사용량 및 활동

설정 및 알림

팀

프로젝트

번역 및 더빙

전사문 및 편집

텍스트 음성 변환

음성 합성용 음성

더빙 음성

음성 전사

자막 및 캡션

이미지

썸네일

폴더

용어집

웹훅

게시

요청 상태

OAuth 및 MCP 프로토콜

인증 및 권한

매개변수

요청 예제

응답

결과가 저장된 완료된 요청

완료된 세그먼트 편집 요청

결과가 보관되지 않은 완료된 요청

실패한 저장 요청

중단된 저장 요청

작업 참고 사항

사용량

오류

​인증 및 권한

​매개변수

​요청 예제

​응답

​결과가 저장된 완료된 요청

​완료된 세그먼트 편집 요청

​결과가 보관되지 않은 완료된 요청

​실패한 저장 요청

​중단된 저장 요청

​작업 참고 사항

​사용량

​오류

인증 및 권한

매개변수

요청 예제

응답

결과가 저장된 완료된 요청

완료된 세그먼트 편집 요청

결과가 보관되지 않은 완료된 요청

실패한 저장 요청

중단된 저장 요청

작업 참고 사항

사용량

오류