문서 섹션

시뮬레이션 작업

계산기는 요청 하나로 답합니다. 시뮬레이터는 그렇지 않습니다(풀웨이브 해석은 몇 분에서 몇 시간이 걸립니다). 그래서 작업으로 제출하고 폴링합니다. 작업 유형마다 /api/py/v1/jobs/types에서 매개변수 계약을 공개합니다. 모든 매개변수의 타입, 단위, 범위나 선택지, 기본값, 필수 여부와, 이용 중인 요금제의 제한입니다. 브라우저 양식은 이 문서로 만들어지고 워커도 이 문서로 검증하므로, 이 페이지에서 매개변수 이름을 옮겨 적지 말고 이 문서를 읽으세요.

엔드포인트

작업 엔드포인트
엔드포인트	하는 일	자격 증명
GET /api/py/v1/jobs/types	모든 시뮬레이션 작업 유형과 각각의 요금제, 시간 상한, 제한, 업로드.	없음
GET /api/py/v1/jobs/types/{job_type}	작업 유형 하나의 매개변수 계약(JSON Schema).	없음
POST /api/py/v1/jobs/estimate	작업을 제출하지 않고, 비용과 실행 시간을 견적 냅니다.	없음
POST /api/py/v1/upload	작업 입력 파일용 서명된 양식.	API 키 또는 로그인한 세션
POST /api/py/v1/jobs	시뮬레이션 작업을 제출합니다.	선택: API 키
GET /api/py/v1/jobs/{job_id}	작업의 상태와 진행률, 완료되면 결과 링크.	제출한 것과 같은 신원
GET /api/py/v1/jobs	계정의 모든 키로 제출한, 호출자의 최근 작업.	API 키 또는 로그인한 세션

제출과 폴링

계약을 읽고, params(업로드한 파일이 있으면 inputFileKeys도)와 함께 작업을 POST로 보내면, jobId와 함께 202를 받습니다. 키를 사용하면 제출은 할당량에서 호출 1회로 집계됩니다.

제출한 것과 같은 신원으로 GET /api/py/v1/jobs/{jobId}를 폴링합니다. 상태에는 progress, stage, finishedAt, elapsedSeconds, errorKind가 담기고, 완료되면 서명된 resultUrl이 추가됩니다. GET /api/py/v1/jobs는 계정의 어느 키로 제출한 것이든 포함해 최근 작업을 나열합니다. Python 라이브러리는 웹 앱과 같은 방식으로 폴링합니다. job.wait()는 바로 확인한 뒤, 작업이 계속되는 동안 2초, 5초, 15초마다 확인합니다.

작업 유형

작업 유형은 13개입니다. 각 유형의 매개변수 목록은 /api/py/v1/jobs/types/{jobType}에 있습니다.

작업 유형
jobType	시뮬레이터	업로드
`antenna_sim`매개변수 14개	와이어 안테나 시뮬레이터 (NEC-2)	없음
`emi_radiated`매개변수 11개	EMI 방사 방출 추정기	없음
`eye_diagram`매개변수 11개	S-파라미터를 이용한 아이 다이어그램	필수, 최대 1 × .s2p / .s4p
`fdtd_sparam`매개변수 17개	FDTD 송전선 시뮬레이터	없음
`filter_monte_carlo`매개변수 15개	RF 필터 몬테카를로 분석	없음
`impedance_match`매개변수 14개	광대역 임피던스 매칭 신시사이저	선택, 최대 2 × .s2p / .s1p
`magnetics_optimizer`매개변수 14개	마그네틱 및 트랜스포머 설계 옵티마이저	없음
`pdn_impedance`매개변수 16개	PDN 임피던스 분석기 및 디커플링 커패시터 옵티마이저	없음
`radar_detection`매개변수 15개	레이더 탐지 성능 몬테카를로	없음
`rf_cascade`매개변수 8개	RF 캐스케이드 버짓 분석기	선택, 최대 12 × .s2p
`sat_link_budget`매개변수 14개	위성 및 지상파 링크 예산	없음
`smps_control_loop`매개변수 36개	SMPS 제어 루프 안정성 분석기	없음
`sparam_pipeline`매개변수 3개	S-파라미터 분석 파이프라인	필수, 최대 4 × .s1p / .s2p / .s3p / .s4p

작업 비용 견적

POST /api/py/v1/jobs/estimate는 제출할 때와 같은 본문을 받아, 작업이 실행될 실행 환경, 예상 소요 시간, 그 환경의 예산에 들어맞는지, 그리고 유료 실행 환경에서는 기록될 크레딧을 알려 줍니다. 견적은 과금되지 않고, 키도 필요 없으며, 제출과 같은 검사를 거치므로 제출이 거부될 때에만 거부됩니다. 크레딧은 표시되고 기록되지만 아직 과금되지는 않습니다.

요청이 거부되는 경우

제출은 대기열에 넣거나 과금하기 전에 계약에 비추어 검사됩니다. 계약을 벗어난 요청은 처음 발견된 것 하나가 아니라 문제가 있는 모든 매개변수를 알려 주는 400으로 응답하며, 대기열에 들어가지 않고 할당량도 쓰지 않습니다. 알 수 없는 매개변수 키는 무시되지 않고 거부됩니다.

오류 종류

모든 실패에는 메시지 옆에 errorKind가 붙습니다. 거부된 제출이든, 접수된 뒤 실패한 작업이든 마찬가지입니다. 이는 정해진 값의 집합입니다. 메시지 문구는 사람이 읽기 위한 것이며 바뀔 수 있으므로, 문구가 아니라 이 값으로 분기하세요.

오류 종류
errorKind	의미
invalid_request	매개변수가 없거나, 타입이 잘못되었거나, 범위를 벗어났거나, 선언된 선택지에 없거나, 이 작업 유형의 매개변수가 아닙니다. 400 본문에 문제가 있는 모든 매개변수가 나열됩니다.
too_large	요청은 계약 범위 안에 있지만, 이 요금제의 실행 환경이 처리할 수 있는 규모를 넘습니다. 문제의 규모를 줄이세요.
not_available	요청이 이 요금제에 포함되지 않은 모드나 기능을 요구합니다. 메시지에 요금제에 포함된 것이 표시됩니다.
rate_limited	동시 작업 한도나 월간 할당량을 다 썼습니다. Retry-After가 함께 오며, 월간 할당량인 경우 resetAt도 함께 옵니다.
timeout	작업이 그 유형의 시간 상한을 넘었습니다. 과금되지 않습니다.
interrupted	실행이 끝나기 전에 멈췄습니다(워커가 교체되었거나 태스크가 중지됨). 과금되지 않습니다.
result_expired	작업은 완료되었지만 결과가 더 이상 저장되어 있지 않습니다. 상태는 계속 completed이고 resultUrl은 없습니다.
transient	서비스가 그 순간 요청을 받거나 확인하지 못했습니다. 대기열에 들어가지도 과금되지도 않았습니다. 다시 시도하세요.
fault	서비스가 계산 중에 실패했습니다. 메시지에 실패한 단계가 표시됩니다. 과금되지 않습니다.

제한, 중복, 보존 기간

동시 실행

호출자마다 대기 중이거나 실행 중인 작업은 동시에 3개까지입니다. 이를 넘으면 API는 Retry-After, 그리고 pending과 limit이 담긴 본문과 함께 429로 응답합니다.

중복 제출

같은 호출자가 60초 안에 같은 요청을 보내면 기존 작업을 실제 상태 그대로 반환하므로, 이미 실패한 작업은 그 이유와 함께 실패로 돌아옵니다. 그래도 다시 실행하려면 Idempotency-Bypass: true를 보내세요.

업로드

POST /api/py/v1/upload에는 키나 로그인한 세션이 필요하며, 5분 동안 유효한 서명된 POST 양식을 반환합니다. 파일당 최대 10 MB이며, 양식 자체가 이를 강제합니다. 허용 형식: .s1p .s2p .s3p .s4p .s6p .s8p .snp .csv .txt. 업로드한 객체는 24시간 동안 보관되므로, 그 파일을 쓰는 작업은 당일 안에 제출하세요. 양식은 주소당 분당 20개까지 발급됩니다.

결과

기한은 두 가지입니다. resultExpiresAt은 결과 자체가 사라지는 시점으로, 무료 요금제에서는 30일, Pro와 API에서는 무기한입니다. resultUrlExpiresIn은 서명된 resultUrl이 유효한 기간으로, 15분입니다. 새 링크는 다시 폴링해서 받고, URL은 캐시하지 마세요. 결과가 사라진 뒤에도 상태는 completed로 남으며, 종류는 result_expired가 되고 URL은 없습니다.

매개변수를 생략하는 호출자에게 바뀐 점

각 작업 유형에는 매개변수 정의가 하나뿐이며, 핸들러 자체의 대체값은 없어졌습니다. 모든 필드를 보낸다면 바뀐 것은 없습니다. 이 중 하나를 생략한다면 사용되는 값이 이전과 다르고, 따라서 답도 달라집니다.

바뀐 기본값
jobType	매개변수	이전	현재
`rf_cascade`	`nfSpec_db`	10 dB	6 dB
`rf_cascade`	`inputPower_dbm`	−60 dBm	−70 dBm
`rf_cascade`	`bandwidth_hz`	1 MHz	10 MHz
`rf_cascade`	`stages`	"[]"	필수 — 기본값 없음
`smps_control_loop`	`toleranceDistribution`	uniform	gaussian
`filter_monte_carlo`	`freqCutoff`	1 MHz	1 GHz
`impedance_match`	`freqStart`	1 MHz	800 MHz
`impedance_match`	`freqStop`	100 MHz	1.2 GHz
`antenna_sim`	`freq (instant solve)`	145 MHz	146 MHz
`pdn_impedance`	`portX_mm`	기판 중앙(boardWidth_mm / 2)	3분의 1 지점(boardWidth_mm / 3)
`pdn_impedance`	`portY_mm`	기판 중앙(boardLength_mm / 2)	3분의 1 지점(boardLength_mm / 3)

알 수 없는 매개변수 키는 이전에는 버려지고 기본값으로 응답했습니다. 이제는 거부되며, 거부 내용에 그 작업 유형이 받는 키 목록이 담깁니다.

샘플링하는 작업 유형(filter_monte_carlo와 그 밖의 최적화기)에서는 난수 시드가 제출한 본문에서 도출되므로, 같은 설계라도 본문의 키 구성이 다르면 다른 표본을 뽑습니다. 매개변수를 생략하는 것과 기본값으로 보내는 것은 솔버에게는 같은 요청이지만 같은 본문은 아닙니다. 그래서 웹 양식에서 실행한 것과 이 API로 실행한 것은 표본 오차 범위 안에서 다를 수 있습니다. 실행을 정확히 고정하려면 randomSeed를 보내세요.

2026년 9월 릴리스의 변경 사항

기존 통합에 영향을 주는 동작 변경입니다. 모든 매개변수를 보내고 메시지 문구가 아니라 errorKind를 확인한다면, 보게 될 차이는 이것들뿐입니다. 이후의 변경과 각 변경의 공지 날짜는 API 변경 기록에 있습니다.

바뀐 내용

알 수 없는 매개변수 키와 범위를 벗어난 값은, 버려지거나 잘린 채 그대로 응답하는 대신, 제출할 때 문제가 된 매개변수를 알려 주는 400으로 거부됩니다.
필드를 생략하는 호출자에게 매개변수 기본값 11개가 바뀌었습니다. 위의 표를 참고하세요.
월간 할당량을 다 쓰면 이제 HTTP 402(errorKind rate_limited)이며, Retry-After와 resetAt이 함께 옵니다. 401이나 단순한 429가 되는 일은 없습니다. 이는 API 키의 월간 할당량과 FDTD 해석 모드의 할당량 모두에 해당합니다.
업로드에는 이제 로그인한 세션이나 API 키가 필요하며, 익명 요청은 아무것도 저장되기 전에 401을 받습니다. 익명 무료 실행 환경에서는 파일 입력 도구 두 가지(eye_diagram, sparam_pipeline)를 아예 쓸 수 없게 됩니다. 둘 다 업로드한 파일 없이는 실행되지 않기 때문입니다.
API 키로 제출한 작업은 이제 그 키 소유자의 계정에 속합니다. 키 ID나 제출한 IP만이 아니라 소유자 기준으로 권한을 확인하며, 소유자의 대시보드 작업 목록에 표시됩니다.
완료된 결과에는 이제 계산된 값과 함께 warnings와 provenance(method, version, seed, 실제로 사용된 정규화된 입력)가 담깁니다.
모든 실패(거부된 제출과, 접수된 뒤 실패한 작업)에 이제 errorKind가 붙습니다. 위의 정해진 집합을 참고하세요.
실행 도중 워커가 멈춘(교체되었거나 태스크가 중지된) 작업은 이제 멈춘 채로 남지 않고 interrupted 종류로 실패 처리되며, 그 작업에 대한 과금은 해제됩니다.
결과는 그 기록에 적힌 기간 동안 정확히 보관됩니다. 위의 '결과' 카드에서 resultExpiresAt을 참고하세요.
임피던스 합성기의 Auto 토폴로지는 이제 다섯 가지 토폴로지를 모두 비교해 최악의 경우 반사 손실이 가장 좋은 것을 반환합니다. 이전에는 빠른 모드에서도, 고급 설정의 기본값에서도 항상 L형 회로를 만들었습니다.
임피던스 합성기는 이제 maxQ와 componentSeries를 반영합니다. 이전에는 둘 다 받기만 하고 조용히 무시했습니다.
E 계열 표준값으로 맞출 때, 가수가 약 9.55를 넘으면 내림하지 않고 다음 데케이드의 첫 값으로 올림합니다(9.9 nF → 10 nF). 같은 입력이라도 임피던스 정합 설계나 필터 몬테카를로 실행에서 부품 값 하나가 바뀔 수 있습니다.
임피던스 페이지에서 내보낸 SPICE 넷리스트에는 이제 이상값이 아니라 표준값(맞춘 값)의 부품이 담기며, 계열을 밝히는 머리글 행이 붙습니다.
전력 인덕터와 결합 인덕터 설계는 이제 다른 입력에서 도출하지 않고, 지정한 인덕턴스와 피크 전류로 치수를 정합니다. 플라이백 변압기와 포워드 변압기는 바뀌지 않습니다. 지정한 피크 전류가 지정한 인덕턴스의 리플과 맞지 않는 요청에는 ripple_exceeds_peak 경고가 붙습니다.
배포 관련 참고: 이번 롤아웃에서는 API 검증기가 워커보다 먼저 배포되었습니다. 그래서 그 사이에 대기열에 들어간 작업 중, 본문에 철자가 틀린 키(이전에는 기본값으로 조용히 받아들이던 것)가 담긴 작업은 끝까지 실행되지 않고 제출 시점에 거부되었습니다.

제출

curl -X POST https://rftools.io/api/py/v1/jobs \
  -H "X-API-Key: $RFTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "sat_link_budget",
    "params": {
      "latitude_deg": 40.7,
      "longitude_deg": -74,
      "frequency_ghz": 12
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

job = client.submit_job("sat_link_budget", {"latitude_deg": 40.7, "longitude_deg": -74, "frequency_ghz": 12})
job = job.wait(timeout=600)
print(job.status, job.result())

const response = await fetch("https://rftools.io/api/py/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jobType": "sat_link_budget",
    "params": {
      "latitude_deg": 40.7,
      "longitude_deg": -74,
      "frequency_ghz": 12
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "jobType": "sat_link_budget",
	  "params": {
	    "latitude_deg": 40.7,
	    "longitude_deg": -74,
	    "frequency_ghz": 12
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/jobs", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

application/json

{
  "jobId": "6f1c2d4e-…",
  "status": "queued",
  "queuePosition": 1,
  "queueTotal": 1
}

대기열에 들어갔습니다. jobId를 폴링하세요.

{
  "errorKind": "invalid_request",
  "detail": [
    {
      "param": "frequency_ghz",
      "value": 900,
      "reason": "Frequency (frequency_ghz) must be between 0.1 and 100 GHz (got 900 GHz).",
      "allowed": "0.1 to 100 GHz"
    },
    {
      "param": "longitude_deg",
      "value": null,
      "reason": "Site Longitude (longitude_deg) is required.",
      "allowed": null
    }
  ]
}

계약을 벗어난 모든 매개변수를 한 번에 알려 줍니다. 대기열에 들어가지 않았습니다.

{
  "detail": "You already have 3 jobs queued or running, and the limit is 3. Wait for one to finish.",
  "pending": 3,
  "limit": 3,
  "errorKind": "rate_limited"
}

동시에 실행 중인 작업이 너무 많습니다. Retry-After가 함께 옵니다.

폴링

curl https://rftools.io/api/py/v1/jobs/JOB_ID \
  -H "X-API-Key: $RFTOOLS_API_KEY"

import os

import httpx

response = httpx.get(
    "https://rftools.io/api/py/v1/jobs/JOB_ID",
    headers={"X-API-Key": os.environ["RFTOOLS_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch("https://rftools.io/api/py/v1/jobs/JOB_ID", {
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
  },
});
console.log(response.status, await response.json());

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://rftools.io/api/py/v1/jobs/JOB_ID", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

제출하지 않고 견적 내기

curl -X POST https://rftools.io/api/py/v1/jobs/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "fdtd_sparam",
    "params": {
      "traceW": 0.42,
      "subH": 0.51,
      "solveMode": "express"
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

est = client.estimate_job("fdtd_sparam", {"traceW": 0.42, "subH": 0.51, "solveMode": "express"})
print(est.lane, est.wall_seconds, est.within_budget)

const response = await fetch("https://rftools.io/api/py/v1/jobs/estimate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jobType": "fdtd_sparam",
    "params": {
      "traceW": 0.42,
      "subH": 0.51,
      "solveMode": "express"
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{
	  "jobType": "fdtd_sparam",
	  "params": {
	    "traceW": 0.42,
	    "subH": 0.51,
	    "solveMode": "express"
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/jobs/estimate", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}