이미지, 비디오, 음악 및 음성
텍스트에 사용하는 키로 이미지, 비디오, 음악, 음성을 만들고 녹음을 텍스트로 변환할 수 있으며, 이 모든 것이 동일한 잔액에서 차감됩니다. 모델 표 (또는 ?type=image, ?type=music, ?type=audio)에서 모델을 선택하세요. 각 모델 페이지에는 가격, 유형 및 작동하는 요청 예시가 나와 있습니다.
| 원하는 것 | 경로 | 원본 사진 입력 위치 |
|---|---|---|
| 프롬프트에서 새 이미지 | POST /v1/images/generations |
(없음) |
| 편집된 사진 | POST /v1/images/edits |
image (또는 image_url, input_images, images) |
| 프롬프트에서 비디오 | POST /v1/video/generations |
(없음) |
| 사진에서 시작하는 비디오 | POST /v1/video/generations |
image_url (첫 프레임); end_image_url (마지막 프레임) |
| 참조 사진에서 비디오 | POST /v1/video/generations |
input_images ("role": "reference"와 함께) |
| 사진에 대한 텍스트 답변 | POST /v1/chat/completions |
messages[].content의 image_url 부분 |
| 음악 | POST /v1/music/generations |
(없음) |
| 텍스트에서 음성 | POST /v1/audio/speech |
(없음) |
| 녹음에서 텍스트 | POST /v1/audio/transcriptions |
(없음; 녹음은 file에 입력) |
원본 사진은 https:// 링크, data: URI (data:image/png;base64,iVBORw0…) 또는 PNG, JPEG, WebP의 일반 base64이며, 요청당 최대 8까지 가능합니다. 이미지 경로는 멀티파트 업로드(아래 참조)도 지원합니다. 링크는 공개 https:// 링크여야 합니다. http:// 링크는 거부됩니다. 리디렉션되는 링크(예: https://picsum.photos/640/360)는 최대 5회까지, 그리고 다른 공개 https:// 링크로만 추적되며, 모델은 최종 도착한 링크를 받습니다. 사진으로 연결되지 않거나 사용할 수 없는 곳으로 리디렉션되는 링크는 어떠한 보류나 요금 청구 없이 400 invalid_image_url으로 거부됩니다. 인라인으로 전송된 사진은 요청 크기를 늘립니다. 10 MB 미만으로 유지하거나 링크를 보내세요.
채팅 메시지(messages[].content의 image_url)에서 링크(https:// 또는 http://)는 MartLLM에 의해 열리고 data: URL로 모델에 전송됩니다. 대부분의 비전 모델은 그것만 받기 때문입니다. 각 사진은 최대 20 MB(요청당 40 MB)까지 가능하며, 리디렉션은 최대 5회까지, 공개 주소로만 추적됩니다. Gemini 모델은 링크를 있는 그대로 받습니다. 사진으로 연결되지 않는 링크는 400 invalid_image_url으로 거부되며, 요금은 청구되지 않습니다.
이미지 만들기
이미지는 답변으로 돌아옵니다.
curl https://api.martllm.com/v1/images/generations \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "venice/z-image-turbo", "prompt": "a red apple on a white table", "n": 1, "size": "1024x1024"}'
{ "created": 1792429247, "data": [{ "url": "https://api.martllm.com/v1/media/artifacts/<id>/0" }],
"usage": { "cost_usd": 0.0099, "max_cost_usd": 0.0109 } }
usage.cost_usd는 이미지 비용입니다 (X-UberLLM-Cost-USD 헤더에도 있습니다). 가격이 아직 알려지지 않은 드문 답변의 경우 null입니다. 제공업체가 청구한 금액을 지불하며, 이를 위해 보류된 max_cost_usd를 초과하지 않습니다.
response_format는 /v1/images/generations와 /v1/images/edits 모두에 대해 기본적으로 url입니다. 대신 답변 안에 이미지를 받으려면 "response_format": "b64_json"를 보내세요. 모델이 이미지 자체를 반환하면, MartLLM은 이를 24시간 동안 귀하의 계정 파일로 보관하고 해당 링크(https://api.martllm.com/v1/files/file_…/content)로 답변합니다. 이 링크는 나중에 편집할 원본 이미지로도 작동합니다. 동일한 키로 URL을 다운로드하세요:
curl -L -o image.png -H "Authorization: Bearer $UBERLLM_API_KEY" \
"https://api.martllm.com/v1/media/artifacts/<id>/0"
n는 1에서 10까지입니다.
사진 편집하기
편집 모델(ID는 보통 -edit로 끝납니다)을 사용하고, 원본 사진을 image에 보내세요:
curl https://api.martllm.com/v1/images/edits \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "google/nano-banana-pro-edit", "prompt": "make the sky a sunset",
"image": "https://example.com/skyline.png"}'
동일한 사진은 다음 형식으로 입력할 수 있습니다:
"image": "data:image/png;base64,iVBORw0…""image_url": "https://…""input_images": ["https://…", "https://…"]: 첫 번째는 편집할 사진이고, 나머지는 참조용입니다. 항목은{"url": "…", "role": "reference"}일 수도 있습니다."images": [{"image_url": "https://…"}], OpenAI SDK가 보내는 형식
일반 base64도 작동하며, "input_image"는 "image"으로 읽힙니다.
또는 OpenAI의 이미지 편집처럼 파일을 업로드할 수도 있습니다:
curl https://api.martllm.com/v1/images/edits \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-F model=google/nano-banana-pro-edit -F prompt="make the sky a sunset" \
-F [email protected]
원본 사진이 없는 편집 요청은 400 image_required 오류와 함께 거부됩니다. 마스크(인페인팅)는 지원되지 않습니다.
사진 한 번만 업로드하세요
/v1/files에 사진을 업로드하고, 매번 요청에 보낼 필요 없이 24시간 동안 원하는 만큼 많은 요청에 사용하세요:
curl https://api.martllm.com/v1/files \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-F [email protected]
{ "id": "file_3f9c…", "object": "file", "bytes": 482113, "content_type": "image/png",
"filename": "skyline.png", "created_at": 1792540800, "expires_at": 1792627200,
"url": "https://api.martllm.com/v1/files/file_3f9c…/content" }
그런 다음 ID 또는 url을(를) 원본 사진이 들어가는 모든 곳에 넣으세요: "image": "file_3f9c…", "image": {"file_id": "file_3f9c…"}, "image_url": "file_3f9c…", input_images의 항목, 또는 비디오의 시작 프레임. 귀하의 계정만 해당 파일을 사용할 수 있습니다.
- PNG, JPEG, WebP, GIF, HEIC 또는 AVIF, 각 파일당 최대 10MB, 계정당 한 번에 최대 500개까지 보관됩니다.
- 24시간 동안 보관된 후 삭제됩니다.
GET /v1/files/{id}은(는) 하나를 설명하고,GET /v1/files/{id}/content은(는) 다운로드하며,DELETE /v1/files/{id}은(는) 지금 삭제합니다.
영상 만들기
영상은 1분 이상 소요되므로, 시작하고, 확인하고, 다운로드하는 작업입니다.
1. 시작하기
curl https://api.martllm.com/v1/video/generations \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"model": "fal-ai/vidu/q3/text-to-video/turbo", "prompt": "a red ball bouncing on green grass",
"duration_seconds": 5, "models": ["fal-ai/kling-video/v3/standard/text-to-video"]}'
models은 선택 사항입니다: 첫 번째 모델에 현재 무료 제공자가 없을 때만 백업 모델이 순서대로 시도되므로, 바쁜 순간에도 요청이 실패하지 않습니다 (대체 모델 참조). 위 영상은 약 1분 정도 소요되며 약 $0.33의 비용이 듭니다.
사진으로 시작하려면, image-to-video 모델을 사용하고 image_url을 추가하세요:
-d '{"model": "bytedance/seedance-2-0-image-to-video", "prompt": "slow push-in as the waves roll",
"image_url": "https://example.com/first-frame.png", "duration_seconds": 5}'
두 장의 사진을 혼합하는 모델은 end_image_url (마지막 프레임)도 받습니다.
텍스트만으로는 영상을 만들 수 없는 image-to-video 또는 reference-to-video 모델은 요청에 사진이 없을 경우, 요금이 부과되기 전에 400 image_required으로 거부됩니다.
reference-to-video 모델은 input_images에 있는 사진을 받습니다:
-d '{"model": "pixverse/pixverse-c1-reference-to-video", "prompt": "the cat walks across the room",
"input_images": [{"url": "https://example.com/cat.png", "role": "reference"}],
"aspect_ratio": "16:9", "duration_seconds": 5}'
모델이 제공하는 다른 필드: resolution (480p, 720p, 1080p…), aspect_ratio (16:9, 9:16, 1:1…) 및 audio (true / false; 사운드 설정이 없는 모델에는 이 설정이 전송되지 않으며 항상 하던 대로 클립을 만듭니다).
스키마에 aspect_ratios이 없는 image-to-video 모델 (대부분의 Kling, Veo, Wan 및 Seedance image-to-video 모델)은 원본 사진의 형태로 클립을 만듭니다. 원하는 형태를 이미 가진 사진을 보내고 (세로 클립의 경우 9:16로 자르기) aspect_ratio를 제외하세요. 그러한 모델에 전송된 형태는 요금이 부과되기 전에 400 invalid_request로 응답됩니다 ("aspect_ratio": "auto"은 허용되며 제외하는 것과 동일한 의미입니다).
reference-to-video 모델은 형태가 필요하므로, aspect_ratio을 제외하면 16:9로 전송됩니다 (또는 모델이 16:9를 만들지 않는 경우 모델의 첫 번째 형태로); 모델의 스키마에 해당 기본값이 표시됩니다. 각 모델의 선택 사항은 GET /v1/models/<model id>에 의해 나열됩니다 (각 모델의 옵션 참조).
각 모델은 특정 클립 길이, 해상도 및 형태만 만듭니다. 모델이 만들지 않는 것에 대한 요청은 요금이 부과되기 전에 모델이 만드는 것들을 나열하는 메시지와 함께 거부됩니다.
HTTP 202:
{
"id": "6f1c…",
"object": "media.job",
"kind": "video",
"status": "queued",
"model": "fal-ai/vidu/q3/text-to-video/turbo",
"estimated_cost_usd": 0.32725,
"estimated_cost_usdc": "327250",
"max_cost_usd": 0.359975,
"max_cost_usdc": "359975",
"poll_url": "/v1/video/generations/6f1c…",
"cancel_url": "/v1/video/generations/6f1c…"
}
model은 작업을 수행한 모델입니다 (첫 번째 모델이 할 수 없을 때 models의 백업). _usdc으로 끝나는 비용은 100만분의 1달러 단위입니다 (327250 = $0.33). estimated_cost_usd는 예상 가격입니다. 이는 요청하신 내용의 정가로 시작합니다 (validate 및 POST /v1/quote은 cost_usd로 응답합니다: 현재 모델 가격에 요청된 해상도의 초, 이미지 또는 기타 단위를 곱한 값). 작업을 수행하는 판매자가 귀하의 요청에 대해 그 이상을 청구할 것으로 예상하는 경우, estimated_cost_usd는 대신 해당 판매자의 금액입니다: 일반적으로 이 첫 번째 응답부터, 그리고 늦어도 실행 중인 작업의 나중 GET에 표시됩니다 (일부 작업은 시작 후 몇 초 후에 판매자를 배정받으며, 다른 판매자로 이동된 작업은 해당 판매자의 가격이 적용됩니다). 이 금액은 max_cost_usd을 넘지 않고 항상 오르기만 합니다. 작업은 제공자가 청구한 대로 청구됩니다: 일반적으로 예상 금액 이하이며, 드문 경우 더 많을 수 있습니다 (판매자가 종료 시에만 가격을 설정하는 사진으로 만든 클립). max_cost_usd는 작업에 대해 귀하의 잔액에서 보류되는 금액입니다: 작업이 실행 중일 때와 종료된 후에도 동일한 금액이며, 작업에 청구되는 최대 금액입니다. 시작한 판매자가 작업을 놓치고 다른 판매자가 인계받는 경우에도 이 금액 이상으로 청구되는 작업은 없습니다: 귀하의 max_cost_usd보다 비용이 더 많이 드는 판매자는 사용되지 않습니다. second당 가격이 책정된 비디오 모델은 클립의 초당 청구되며; job당 가격이 책정된 모델은 비디오당 해당 비용이 듭니다.
2. 확인하기 매 5–10초마다:
curl -H "Authorization: Bearer $UBERLLM_API_KEY" \
https://api.martllm.com/v1/video/generations/<job id>
작업이 실행 중일 때는 HTTP 202, 작업이 완료되면 HTTP 200:
{
"id": "6f1c…",
"status": "succeeded",
"results": [{ "artifact_index": 0, "url": "https://api.martllm.com/v1/media/artifacts/6f1c…/0",
"content_type": "video/mp4", "duration_seconds": 5 }],
"usage": { "cost_usdc": "40000", "cost_usd": 0.04 }
}
모델은 파일이 준비된 직후, 일반적으로 30초 이내에 작업의 정확한 요금을 보고합니다. 그때까지 succeeded 작업은 "usage": { "cost_usd": null, "cost_pending": true }을 표시합니다; 몇 초 후에 다시 요청하세요. 30분 이내에 요금이 나오지 않으면, 작업은 정가 (estimated_cost_usd)로 청구되며 usage.cost_note에 그렇게 표시됩니다.
3. 다운로드하기
curl -L -o video.mp4 -H "Authorization: Bearer $UBERLLM_API_KEY" \
https://api.martllm.com/v1/media/artifacts/<job id>/0
더 이상 필요 없는 작업을 중지하려면 DELETE /v1/video/generations/<job id>을 요청하세요. 저희는 제공자에게 중지를 요청합니다; 이미 만들어진 작업은 평소와 같이 청구되며, 중지된 작업은 canceled로 종료되고 비용이 들지 않습니다.
Fal 비디오 모델
ID가 fal-ai/로 시작하는 모델은 Fal에서 Fal 자체 가격보다 저렴하게 실행됩니다. 현재 마켓플레이스에서 가장 저렴한 Fal 판매자의 할인 가격을 제외한 Fal 가격을 지불합니다 (2026년 10월 30일에서는 15% 할인; 해당 판매자가 판매할 때마다 25% 할인). 가격은 요청하는 내용(초당 해상도 요율, 클립에 사운드 유무)에 따라 결정되므로, 작업 시작 시 비용을 알 수 있으며 estimated_cost_usd가 정확히 청구됩니다. 실패한 작업에는 비용이 청구되지 않습니다. 작업 중단은 최선을 다하지만, Fal이 이미 클립을 생성했다면 비용이 청구됩니다.
curl https://api.martllm.com/v1/video/generations \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "fal-ai/wan/v2.7/text-to-video", "prompt": "a woman twirls at a garden party at night",
"duration_seconds": 15, "resolution": "720p", "aspect_ratio": "9:16"}'
Fal 자체의 초당 가격 (귀하의 가격은 실시간 할인을 제외한 가격입니다; 각 모델 페이지 GET /v1/models 및 POST /v1/quote에서 현재 정확한 가격을 확인할 수 있습니다):
| 모델 | 길이 (초) | Fal의 초당 가격, 시작 |
|---|---|---|
fal-ai/wan/v2.7/text-to-video, …/image-to-video |
2–15 | 720p $0.10 · 1080p $0.15 |
fal-ai/kling-video/v3/standard/text-to-video, …/image-to-video |
3–15 | $0.084 · 사운드 포함 $0.126 |
fal-ai/kling-video/v3/pro/text-to-video, …/image-to-video |
3–15 | $0.112 · 사운드 포함 $0.168 |
fal-ai/kling-video/o3/standard/text-to-video, …/image-to-video |
3–15 | $0.084 · 사운드 포함 $0.112 |
fal-ai/kling-video/v2.6/pro/text-to-video, …/image-to-video |
5, 10 | $0.07 · 사운드 포함 $0.14 |
fal-ai/veo3.1/fast, fal-ai/veo3.1/fast/image-to-video |
4, 6, 8 | 720p/1080p $0.10 · 사운드 포함 $0.15 · 4k $0.30 |
fal-ai/veo3.1, fal-ai/veo3.1/image-to-video |
4, 6, 8 | 720p/1080p $0.20 · 사운드 포함 $0.40 · 4k $0.40 |
fal-ai/veo3.1/lite |
4, 6, 8 | 720p $0.03 · 사운드 포함 $0.05 · 1080p $0.05 |
fal-ai/ltx-2.3/text-to-video/fast, …/image-to-video/fast |
6, 8, 10 | 1080p $0.06 · 1440p $0.12 · 2160p $0.24 |
fal-ai/ltx-2.3/text-to-video |
6, 8, 10 | 1080p $0.08 |
fal-ai/minimax/hailuo-02/standard/text-to-video, …/image-to-video |
6, 10 | 768P $0.045 · 512P (이미지) $0.017 |
fal-ai/vidu/q3/text-to-video/turbo, …/image-to-video/turbo |
1–16 | 360p/540p $0.035 · 720p/1080p $0.077 |
fal-ai/vidu/q3/text-to-video, …/image-to-video |
1–16 | 360p/540p $0.07 · 720p/1080p $0.154 |
각 가격은 Fal 자체 가격입니다; 작업 시작 시 할인이 적용됩니다. 가장 저렴한 판매자가 작업을 거부하면, 더 비싼 판매자가 작업을 수행하며 해당 판매자의 가격으로 작업이 청구됩니다. 이 경우 응답 시 estimated_cost_usd를 초과하지 않습니다.
일부 모델은 판매자 할인에 명시된 것보다 적은 비용이 듭니다. 매 6시간마다 지난 7일 동안 마켓플레이스가 각 모델에 대해 청구한 금액을 동일한 작업에 대한 Fal의 가격과 비교합니다. 해당 기간 동안 최소 20개의 작업을 수행한 모델은, 더 낮은 경우 실제 점유율에 5%를 더한 가격으로 책정됩니다. 모델 페이지 /v1/models와 청구서 모두 동일한 가격을 사용합니다. 해당 수치가 3일보다 오래된 경우, 판매자 할인이 다시 적용됩니다.
다음 필드는 당사에서 제공합니다: duration_seconds, resolution, aspect_ratio, audio 및 image_url (또는 input_images). Fal 자체 표기법 (duration, generate_audio, start_image_url)도 작동합니다. Kling, Veo 및 Kling 2.6은 "audio": false을 보내지 않는 한 사운드를 추가합니다.
작업 상태
status |
HTTP | 의미 |
|---|---|---|
queued |
202 | 접수됨, 모델이 작업을 시작하기를 대기 중 |
running |
202 | 생성 중. 모델이 진행 상황을 보고하면 progress가 0에서 1로 변경됨 |
succeeded |
200 | 완료됨. results[].url 다운로드 |
failed |
200 | 생성되지 않음. error.message에 이유가, error.retryable에 재시도 가능 여부가 안내됨 |
canceled |
200 | 생성되기 전에 중단됨 |
expired |
200 | 시간 내에 완료되지 않음 |
상태값은 이 여섯 가지뿐입니다. failed, canceled, expired에는 비용이 청구되지 않습니다. DELETE는 중단 요청일 뿐 중단을 보장하지는 않습니다. 공급자가 이미 완료한 작업은 succeeded 상태로 종료되며 요금이 청구됩니다.
혼잡할 때는 자동으로 재시도됩니다. 비디오를 제작할 수 있는 공급자가 없거나 현재 너무 혼잡한 경우, MartLLM이 10분 이내에 최대 2회까지 작업을 자동으로 다시 시작합니다. 동일한 작업 ID와 동일한 최대 비용 한도가 유지되며, 작업 시간이 조금 더 걸릴 뿐입니다. 모든 시도가 실패했을 때만 failed 상태가 표시되며, 실패한 작업에는 비용이 청구되지 않습니다.
결과 대기. callback_url를 보내면 작업 완료 시 알려드리며(콜백 참조), 또는 폴링 URL로 510초마다 확인할 수도 있습니다. 비디오는 대부분 15분 정도 걸리며, 길이가 길거나 4K 작업인 경우 더 오래 걸릴 수 있습니다. 정산을 위해 조회를 계속 반복할 필요는 없습니다. 아무도 확인하지 않는 작업이라도 MartLLM에서 정상적으로 완료하여 청구(또는 환불) 처리하며, 대시보드 → API Keys → API 사용량에 표시됩니다.
콜백
비디오 또는 음악 작업에 callback_url를 추가하세요: 공개 호스트의 https:// 링크입니다. 작업이 완전히 종료되면 MartLLM은 작업에서 GET가 반환하는 것과 동일한 JSON과 함께 해당 링크로 POST를 보냅니다.
{ "model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5,
"callback_url": "https://your-app.example/uberllm/jobs" }
- 시기. 작업이 종료되고 요금이 확정되면 한 번:
usage.cost_usd가 설정된succeeded(절대cost_pending아님), 또는failed,canceled또는expired(비용 0). 비용이 도착할 때 다시 전송되지 않습니다. 비용 도착 후에만 전송되기 때문입니다.output_upload_url의 경우에도 업로드가 완료된 후에 콜백이 오므로output_upload.status는 이미delivered또는failed입니다. - 헤더.
Content-Type: application/json,MartLLM-Event: job.succeeded(또는job.failed,job.canceled,job.expired),UberLLM-Event-Id: <job id>:<status>및UberLLM-Signature: t=<unix seconds>,v1=<hex>. - 재시도. 15초 이내에 2xx로 응답하세요. 다른 응답이거나 응답이 없는 경우, 30초, 2분, 10분, 30분, 2시간 후에 다시 시도한 다음 포기합니다. 언제든지 작업을 폴링할 수 있습니다.
- 반복. 메시지가 두 번 이상 도착할 수 있습니다 (예: 응답이 손실된 경우). 이벤트 ID는 동일하게 유지되므로 이미 처리한 메시지는 삭제하세요.
- 상태. 작업 진행 상황은 다음과 같습니다:
"callback": { "status": "delivered", "attempts": 1, "http_status": 200, "delivered_at": 1792540990 }.status은pending,delivered또는failed입니다 (error은 일반 텍스트로 표시됨). - 링크는 공개 호스트에
https://여야 하며, 사용자 이름이나 비밀번호를 포함해서는 안 됩니다. 이 링크는 다시 표시되지 않으며 콜백이 끝나면 삭제됩니다.webhook_url는 동일한 필드로 읽힙니다. 이미지와 음성은 이를 사용하지 않습니다. 응답 자체로 돌아옵니다.
서명 확인
모든 메시지는 계정의 웹훅 비밀로 서명됩니다. 대시보드 → API keys → Webhook signing secret]에서 찾을 수 있습니다. 처음 열 때 생성되며, Replace secret를 통해 즉시 변경할 수 있습니다.
v1은 전체 비밀 (whsec_…)로 키가 지정된 <t>.<raw body>의 헥스 HMAC-SHA256입니다. 수신한 원시 바이트 (JSON 파싱 전)에 대해 계산하고, 상수 시간으로 비교하며, 5분 이상 된 t는 거부하세요.
Node.js (Express):
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.UBERLLM_WEBHOOK_SECRET; // whsec_…
app.post("/uberllm/jobs", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("UberLLM-Signature") || "";
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
const expected = crypto.createHmac("sha256", SECRET)
.update(`${parts.t}.`).update(req.body).digest("hex");
const ok = parts.v1 && parts.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected)) &&
Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
if (!ok) return res.status(400).send("bad signature");
const job = JSON.parse(req.body);
// Drop a repeat: req.get("UberLLM-Event-Id") is the same each time.
console.log(job.id, job.status, job.usage?.cost_usd);
res.sendStatus(204);
});
Python (Flask):
import hashlib, hmac, os, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["UBERLLM_WEBHOOK_SECRET"].encode() # whsec_…
@app.post("/uberllm/jobs")
def uberllm_job():
raw = request.get_data() # the raw bytes, before any JSON parsing
parts = dict(p.split("=", 1) for p in request.headers.get("UberLLM-Signature", "").split(",") if "=" in p)
expected = hmac.new(SECRET, parts.get("t", "").encode() + b"." + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(parts.get("v1", ""), expected) or abs(time.time() - int(parts.get("t", "0"))) > 300:
abort(400)
job = request.get_json()
# Drop a repeat: request.headers["UberLLM-Event-Id"] is the same each time.
print(job["id"], job["status"], job.get("usage", {}).get("cost_usd"))
return "", 204
웹훅으로 알림
알림 이메일은 웹훅으로도 전송될 수 있습니다. 대시보드 → Credits → For developers: also send alerts to a webhook]에서 링크를 설정하거나, PUT /api/v1/billing/alerts {"alerts_webhook_url": "https://…"} (null은 끄기)를 설정하세요. 메시지는 콜백과 동일한 방식으로 서명되고, 재시도되며, 식별됩니다. 본문은 다음과 같습니다.
{ "id": "evt_…", "object": "event", "type": "balance.low", "created": 1792540990,
"data": { "balance_usd": 4.2, "threshold_usd": 5, "message": "Your balance is $4.20, below the $5.00 you set. Requests stop once it runs out.",
"add_credits_url": "https://martllm.com/dashboard/credits" } }
balance.low: 잔액이 저잔액 이메일에 설정한 금액 미만으로 떨어졌습니다. 금액 미만으로 떨어질 때마다 한 번 전송됩니다. 금액을 설정하기 전까지는 아무것도 전송되지 않습니다.hold.not_released: 작업이 종료된 후 15분 이상 작업에 할당된 금액이 계속 보류되었습니다.data.jobs에 해당 목록이 있으며 (id,kind,model,ended_at,held_usd),data.held_usd은 총액입니다. 이 금액은 여전히 귀하의 것이며, 저희 팀에 통보되었습니다.
파일 보관 기간
결과가 생성된 직후 다운로드하세요:
- 동영상 및 음악 파일은 작업이 끝난 후 약 3시간 동안 보관됩니다.
/v1/media/artifacts/…로 연결되는 이미지 링크는 약 15분 동안 보관됩니다./v1/files/…로 연결되는 이미지 링크는 24시간 동안 보관됩니다. 답변 내부에 그림을 포함하여 직접 보관하려면"response_format": "b64_json"를 요청하세요./v1/files에 업로드한 사진은 24시간 동안 보관됩니다.
그 이후에는 다운로드 시 404 artifact_expired으로 응답합니다.
결과를 자체 스토리지로 전송
동영상 또는 음악 작업에 output_upload_url을 추가하세요: presigned S3, R2 또는 Google Cloud Storage 업로드 링크와 같이 HTTP PUT을 허용하는 https:// 링크입니다. 작업이 성공하면 MartLLM은 해당 파일의 콘텐츠 유형과 함께 파일을 그곳에 업로드합니다. 여러 파일을 생성하는 작업의 경우, 파일당 하나의 링크를 순서대로 output_upload_urls로 보내세요 (최대 4개).
{ "model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5,
"output_upload_url": "https://my-bucket.s3.amazonaws.com/ball.mp4?X-Amz-Signature=…" }
그러면 작업 상태에 output_upload이(가) 포함됩니다:
"output_upload": { "status": "delivered", "attempts": 1, "delivered_at": 1792540990,
"files": [{ "artifact_index": 0, "http_status": 200, "bytes": 5242880 }] }
status은(는) 업로드가 완료될 때까지pending입니다. 그 후delivered또는failed(error는 일반적인 단어로 표시됨)가 됩니다.- 업로드 실패 시 30초, 2, 10, 30분 후에 다시 시도됩니다. 그 후
failed으로 표시됩니다. 파일이 보관되는 동안에는results[].url에서 계속 다운로드할 수 있습니다. 링크는 최소 한 시간 동안 유효해야 합니다. - 링크는 공용 호스트에서
https://이어야 하며, 사용자 이름이나 비밀번호가 포함되어서는 안 됩니다. 이 링크는 다시 표시되지 않으며, 업로드가 완료되면 삭제됩니다. - 이미지는 이를 사용하지 않습니다. 이미지는 답변 자체에 포함되어 돌아옵니다.
음악
/v1/music/generations에서 같은 세 단계입니다. curl -OJ는 저희가 보내는 파일 이름으로 트랙을 저장합니다.
음성
텍스트를 입력하면 오디오 파일이 답변으로 돌아옵니다.
curl https://api.martllm.com/v1/audio/speech \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "x-ai/tts-xai-v1", "input": "Hello from MartLLM."}' \
-o speech.mp3
voice, response_format (예를 들어 mp3 또는 wav) 및 speed를 보낼 수도 있습니다.
각 모델에는 고유한 음성이 있습니다 (GET /v1/models/{id}에 목록이 있습니다). best-price:speech 또는 fastest:speech을 사용하면 어떤 모델이 사용될지 미리 알 수 없으므로, 음성이 모델에 맞춰집니다. 모델이 가지고 있는 음성은 유지되며, OpenAI의 이름은 모델이 해당 음성을 가지고 있는 경우 모델의 일치하는 음성에 매핑됩니다 (alloy → af_alloy). 다른 음성이거나 음성이 없는 경우, 모델의 첫 번째 음성이 사용됩니다. 모델 이름을 지정하면, 사용자의 음성은 그대로 전송됩니다.
input의 1K자 단위로 요금이 청구됩니다. 답변은 오디오 파일이며, 해당 X-UberLLM-Cost-USD 헤더에는 비용이 명시되어 있고, X-Request-Id은 활동(Activity)에 나열된 요청 ID입니다. "validate": true, max_cost, metadata, models 및 provider.max_price은 이미지와 동일하게 작동합니다 (요금 안내] 참조).
녹음을 텍스트로 변환하기
녹음 파일을 file 및 model와 함께 양식으로 보내세요:
curl https://api.martllm.com/v1/audio/transcriptions \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-F model=venice/whisper-large-v3 \
-F [email protected]
{ "text": "Hello from MartLLM.", "duration": 4.2,
"usage": { "type": "duration", "seconds": 5, "cost_usd": 0.00055, "max_cost_usd": 0.00726 } }
usage.cost_usd는 비용입니다 (X-UberLLM-Cost-USD 헤더에도 있으며, text, srt, vtt 응답을 위한 유일한 장소입니다). 저희 자체 필드도 양식에 포함되며, 모델에는 절대 전송되지 않습니다: -F max_cost=0.10, -F "metadata[project]=podcast", -F validate=true.
또한 language, prompt, temperature, response_format를 보낼 수 있습니다:
response_format |
얻는 것 |
|---|---|
json (기본값) |
{ "text": …, "duration": …, "usage": … } |
text |
일반 텍스트로 된 단어들 |
srt |
타이밍 정보가 포함된 캡션 파일(SubRip), 비디오 편집기나 광고에 바로 사용 가능 |
vtt |
WebVTT와 동일한 캡션 |
verbose_json |
json 응답과 segments (id, start, end, text, 초 단위) 및 단어별 타이밍을 제공하는 모델의 경우 words |
curl https://api.martllm.com/v1/audio/transcriptions \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-F model=venice/whisper-large-v3 -F response_format=srt -F [email protected] -o captions.srt
1
00:00:00,330 --> 00:00:03,150
This serum is the one thing I use every morning.
2
00:00:03,300 --> 00:00:06,420
It took two weeks to see a change, now I never skip it.
venice/whisper-large-v3는 문장당 하나의 캡션을 제공합니다; elevenlabs/elevenlabs-scribe-v2는 모든 단어의 타이밍을 기록하며, 캡션은 최대 42자 길이의 줄로 나뉘고, 각 문장 뒤에 새 줄이 시작됩니다. 모델이 녹음에 대한 타이밍 정보를 보내지 않으면, srt, vtt, verbose_json는 400 timestamps_unavailable로 응답하며 요금이 부과되지 않습니다. 오디오 형식에 관계없이 분당 요금이 청구됩니다. 파일은 최대 40 MB까지 가능합니다. 형식(mp3, wav, ogg, flac, m4a/mp4, webm, aac)은 파일 이름이 아닌 녹음 자체에서 읽히므로, tmp123.out이라는 이름의 업로드도 작동합니다.
OpenAI SDK로
from openai import OpenAI
client = OpenAI(base_url="https://api.martllm.com/v1", api_key="<your MartLLM key>")
speech = client.audio.speech.create(model="x-ai/tts-xai-v1", voice="eve", input="Hello from MartLLM.")
speech.write_to_file("speech.mp3")
with open("speech.mp3", "rb") as f:
text = client.audio.transcriptions.create(model="venice/whisper-large-v3", file=f)
print(text.text)
결제하는 금액
- 만들어낸 것의 가격: 제공자가 청구한 금액이고 MartLLM 수수료는 없습니다. 이미지 또는 전사 응답과 완료된 작업에는
usage.cost_usd(미국 달러)로 표시됩니다. 무언가를 만들어낸 모든 응답에는X-UberLLM-Cost-USD응답 헤더에도 이 가격이 담깁니다(음성의 경우 응답이 오디오 파일이라 헤더가 유일한 위치입니다). 대시보드 → 활동에 표시됩니다. 보류된 나머지 금액은 돌아옵니다. - 상태가
failed,canceled또는expired인 작업, 또는 실패한 이미지, 음성, 전사 요청에는 결제되지 않습니다. - 요청한 것을 정확히 만들어내는 가장 저렴한 판매자. 많은 이미지 및 비디오 모델에는 판매자가 여러 명 있습니다. 각 요청은 내 설정으로 만들 수 있는 가장 저렴한 판매자에게 가고, 그 판매자가 처리할 수 없으면 다른 판매자에게 갑니다. 모델 목록과 각 모델 페이지에는 현재 가장 저렴한 판매자의 가격이 실시간으로 표시됩니다.
- 키의 라우팅 설정(대시보드 → API keys)은 한 판매자가 더 빠를 때 판매자 사이에서 선택합니다. 최저가는 항상 가장 저렴한 쪽을 선택하고, 기본값도 계속 실패하거나 가장 빠른 것보다 두 배 넘게 느린 경우가 아니면 가장 저렴한 쪽을 선택합니다. 균형은 가장 빠른 것보다 최대 20% 더 느린 것 중 가장 저렴한 쪽을 선택하고, 가장 빠름은 모델의 표시 가격을 넘지 않는 범위에서 가장 빠른 쪽을 선택합니다. 견적과 작업의
estimated_cost_usd에는 설정이 선택한 판매자의 가격이 표시됩니다. 참고: 키의 라우팅 설정. - 잔액과 보류 중인 금액은
GET /v1/balance로 확인하세요(아래).
결제하기 전에 가격 확인하기
이미지, 비디오, 음악 또는 음성 요청에 "validate": true을 추가하세요(전사의 경우 녹음과 함께 validate=true을 폼 필드로 보내세요). 요청은 실제 요청인 것처럼 검사되며(모델, 옵션, 원본 이미지), 아무것도 만들어지지 않고 아무것도 청구되지 않습니다. 그리고 HTTP 200는 표시 가격(cost_usd, 모델 페이지에 표시된 가격이며, 실제로는 제공자가 청구한 금액을 결제하므로 다를 수 있습니다) 기준 비용과 실행 중 보류되는 금액(max_cost_usd, 최대로 청구될 수 있는 금액)을 알려줍니다:
{ "object": "quote", "model": "bytedance/seedance-2-0-image-to-video", "kind": "video",
"valid": true, "cost_usd": 0.2117, "max_cost_usd": 0.4235, "unit": "second", "units": 5, "duration_seconds": 5,
"note": "Nothing was charged. …" }
모델의 판매자가 빠뜨린 설정을 필요로 한다면(예: reference-to-video 모델은 aspect_ratio가 필요), 함께 전송되는 기본값이 모델의 스키마와 견적에 defaults_applied로 표시됩니다. 예: "defaults_applied": {"aspect_ratio": "16:9"}.
거부될 요청은 같은 방식으로 이유와 함께 거부됩니다.
가격을 15분 동안 보류하기
POST /v1/quote은 이미지, 비디오, 음악 또는 음성 요청과 같은 본문을 받고, 표시된 비용(cost_usd), 실행 중 보류되는 금액(max_cost_usd, 최대로 청구될 수 있는 금액), 그리고 quote_id을 응답합니다(전사의 경우 model과 duration_seconds을 보내세요. 전사 자체는 quote_id을 받지 않으므로 max_cost로 상한을 지정하세요):
curl https://api.martllm.com/v1/quote \
-H "Authorization: Bearer $UBERLLM_API_KEY" -H "Content-Type: application/json" \
-d '{"model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5}'
{ "object": "quote", "id": "6f1c…", "quote_id": "6f1c…", "model": "kling/kling-o3",
"kind": "video", "cost_usd": 0.225, "max_cost_usd": 0.495, "unit": "job", "units": 1,
"expires_at": 1792541700, "note": "Nothing was charged. …" }
15분 안에 같은 요청을 "quote_id": "6f1c…"와 함께 보내면 제공자가 청구한 금액으로, 최대 max_cost_usd까지만 청구됩니다. 시작할 때 보류해야 하는 금액이 max_cost_usd을 넘으면 무료로 취소됩니다. 견적 자체에 대해서는 아무것도 청구되거나 보류되지 않습니다.
- 견적 하나로 요청 하나를 시작합니다. 다시 사용하면
409 quote_used을 응답합니다. 모델에 도달하지 못한 작업은 견적을 돌려줍니다. - 요청은 같은 것을 요구해야 합니다. 같은 모델과 같은 설정(프롬프트, 크기, 클립 길이, 원본 이미지 …)이어야 합니다. 그 외에는
400 quote_mismatch와 함께 거부됩니다.max_cost,metadata,output_upload_url는 달라도 됩니다. - 15분이 지나면
400 quote_expired을 응답합니다. 채팅 모델은 token당 청구되며 견적이 없습니다.provider.max_price로 상한을 지정하세요.
대체 모델과 가격 상한
"models": ["model-b", "model-c"]에는 첫 모델이 지금 당장 처리될 수 없거나(no_available_provider) 내 provider.max_price보다 비쌀 때 순서대로 시도할 모델을 지정합니다. 다른 거부는 즉시 응답됩니다. 응답의 model에는 응답을 만든 모델이 지정됩니다(음성 응답은 오디오 파일 자체이므로 활동에 해당 모델이 표시됩니다). quote_id이 있는 요청은 models을 받지 않으며, 전사는 둘 다 받지 않습니다.
"provider": {"max_price": 0.05}은 한 단위(모델의 가격 책정 unit: 이미지, 초, 메가픽셀, 분, 1K 문자 또는 요청)가 미국 달러로 가질 수 있는 최대 비용입니다. 이보다 비싼 모델은 400 max_price_exceeded와 함께 거부되며, 요청은 단위 수의 max_price배를 넘게 청구되지 않습니다. 다른 provider 옵션은 400 unsupported_routing_option와 함께 거부됩니다. 미디어 요청의 판매자 선택은 요청별로 조정할 수 없기 때문입니다.
"model": "best-price:image"(또는 image-edit, text-to-video, image-to-video, music, speech, transcription)은 작업에 현재 사용 가능한 가장 저렴한 모델을 선택하고, fastest:는 측정된 가장 빠른 모델을 선택합니다. 참고: 모델 별칭.
태그
"metadata": {"project": "spring-ads"}(최대 16개의 텍스트 값)은 작업과 함께 저장되고, 상태 응답에 반환되며, 활동과 CSV 내보내기에 표시되고, 모델에는 절대 전송되지 않습니다. 전사의 경우 폼 필드로 보내세요: -F "metadata[project]=spring-ads". 참고: 태그.
상한 설정하기
이미지, 비디오, 음악 또는 음성 요청에 "max_cost"(미국 달러, 예: 0.50)을 보내세요(전사의 경우 폼 필드). 그보다 더 비쌀 수 있으면 400 max_cost_too_low와 함께 거부되고 아무것도 청구되지 않습니다. 비디오 또는 음악 작업의 경우 정확한 상한은 작업이 시작될 때 설정됩니다. 그다음 결과가 내 max_cost을 넘으면 작업은 무료로 취소됩니다. "validate": true을 사용하면 견적에 within_max_cost가 추가됩니다.
두 번 결제하지 않고 재시도
비디오 또는 음악 작업을 시작할 때 Idempotency-Key 헤더(예: UUID 같은, 최대 255자리의 임의의 고유 문자열)를 보내세요. 연결이 끊겼다가 24시간 안에 같은 키로 같은 요청을 다시 보내면 두 번째 작업 대신 같은 작업을 돌려받습니다. 같은 키에 다른 요청을 보내면 409 idempotency_key_reused와 함께 거부됩니다. 이미지, 음성, 전사 요청은 키를 받지 않습니다. 실패한 요청은 청구되지 않았으므로 다시 보내면 됩니다.
잔액
curl -H "Authorization: Bearer $UBERLLM_API_KEY" https://api.martllm.com/v1/balance
{ "balance_usd": 12.40, "held_usd": 0.35, "available_usd": 12.05 }
held_usd는 아직 실행 중인 요청을 위해 할당되었습니다. 해당 요청이 완료되면 (실제 비용을 제외하고) 다시 돌아옵니다. available_usd는 새로운 요청에 사용할 수 있습니다.
모델별 옵션
GET /v1/models?type=image(또는 video, music, speech, transcription,
둘 다의 경우 audio, chat, all; 여러 개를 쉼표로 연결; type이 없으면
목록은 채팅 모델만)은 지금 호출할 수 있는 모델을, 각 모델의 type, 요청을 보낼
endpoints, 그리고 pricing과 함께 나열합니다. GET /v1/models/<model id>는 한 모델을 보여주고, 미디어 모델의 경우
parameters 객체를 보여줍니다: 요청 본문의 JSON Schema로, 지원하는 클립 길이, 해상도, 화면 비율,
크기와 필요한 원본 이미지를 담고 있습니다.
curl -H "Authorization: Bearer $UBERLLM_API_KEY" \
https://api.martllm.com/v1/models/pixverse/pixverse-c1-reference-to-video
pricing에는 usd(현재 unit 하나에 가장 많이 드는 비용)과 list_usd(모델 제작사의
자체 가격)이 있습니다; 채팅 모델에는 input_usd, output_usd, 그리고 각각의 list_ 가격이
1M tokens당 있습니다.
usd는 현재 해당 모델에 대한 일반 요청이 견적되는 가격입니다: 키를 균형(기본값)으로
설정했을 때 요청이 향할 판매자 가격에 저희 수수료를 포함한 금액입니다. 목록과 견적은
같은 코드로 계산되며, 약 30초 이내에 저희 판매자 정보를 반영합니다(판매자가 일시중지되거나,
꺼지거나, 가격을 변경한 경우).
해상도별로 가격이 매겨지는 모델에는 resolutions도 있습니다: 해상도마다 한 행
(동영상의 480p / 720p / 1080p, 이미지의 1K / 2K / 4K), 가장 저렴한 것부터, 각
행에는 usd(해당 해상도에서 1초 또는 1장이 견적되는 금액)과
list_usd이 있습니다. 위의 usd가 가장 저렴한 행입니다. 클립은 요청한 해상도의 가격에
초 수를 곱한 금액으로 청구됩니다:
"pricing": {"usd": 0.100884, "unit": "second", "resolutions": [
{"resolution": "480p", "usd": 0.100884, "list_usd": 0.1287},
{"resolution": "720p", "usd": 0.2268, "list_usd": 0.289},
{"resolution": "1080p", "usd": 0.56133, "list_usd": 0.7107}]}
일부 판매자는 1초가 아니라 클립 전체에 가격을 매깁니다. 이런 행에는 seconds도 있습니다:
해당 usd가 초당 가격으로 적용되는 클립 길이입니다. 이는 가장 비싼 요율
(모델의 가장 짧은 클립)이므로, 더 긴 클립은 초 수의 usd배보다 적게 들고,
길이를 지정하지 않은 요청은 정확히 usd × seconds로 견적됩니다. seconds는
해상도가 한 가지 길이로만 판매되는 경우에도 나타납니다.
{"resolution": "720p", "usd": 0.062344, "list_usd": 0.075, "seconds": 4}
초당 가격은 가장 가까운 $0.000001로 반올림됩니다. 요청의 정확한 가격은
견적을 요청하세요("validate": true).
오류
| HTTP | 코드 | 의미 |
|---|---|---|
| 400 | wrong_endpoint |
예: /v1/video/generations로 전송된 이미지 모델, 이미지 경로로 전송된 채팅 모델, 또는 /v1/audio/transcriptions로 전송된 음성 모델; 메시지에 올바른 경로가 명시됩니다. 요금은 청구되지 않으며, 활동 내역에는 거부됨으로 표시됩니다. |
| 400 | invalid_request |
요청이 잘못되었습니다 (메시지에 이유가 명시됩니다. 예: 모델이 제공하지 않는 길이 또는 누락된 원본 사진) |
| 400 | image_required |
원본 사진이 없는 편집, 또는 이미지-비디오 또는 참조-비디오 모델 요청 |
| 400 | max_cost_too_low |
max_cost보다 비용이 더 많이 들 수 있습니다; 요금은 청구되지 않았습니다 |
| 400 | timestamps_unavailable |
타이밍을 보내지 않은 전사 모델에 srt, vtt 또는 verbose_json을 요청했습니다; 요금은 청구되지 않았습니다 |
| 409 | idempotency_key_reused |
해당 Idempotency-Key가 다른 요청에 사용되었습니다 |
| 400 | quote_mismatch / quote_expired |
요청이 견적된 것과 다르거나, 견적이 15분 이상 경과했습니다 |
| 404 | quote_not_found |
귀하의 계정에 해당 견적이 없습니다 |
| 409 | quote_used |
해당 견적으로 이미 요청이 시작되었습니다 |
| 400 | max_price_exceeded |
이 모델은 provider.max_price보다 단위당 비용이 더 많이 듭니다 |
| 400 | unsupported_routing_option |
max_price 이외의 provider 옵션 |
| 404 | file_not_found |
귀하의 계정에 해당 업로드된 파일이 없거나 만료되었습니다 |
| 413 | file_too_large |
10 MB를 초과하는 업로드 |
| 429 | too_many_files |
500개의 업로드가 이미 보관되어 있습니다; 일부를 삭제하거나 만료될 때까지 기다리세요 |
| 503 | files_unavailable |
현재 업로드를 이용할 수 없습니다 |
| 413 | request_too_large |
요청이 크기 제한(40 MB)을 초과합니다; 사진은 https:// 링크로 보내고 긴 녹음 파일은 분할하여 보내세요 |
| 402 | insufficient_credits |
잔액이 작업의 최대 비용을 충당할 수 없습니다; 메시지에 필요한 금액이 명시됩니다 |
| 404 | model_not_found / not_found |
해당 모델이 없거나, 귀하의 계정에 해당 작업이 없습니다 |
| 404 | artifact_expired |
파일이 더 이상 보관되지 않습니다 (위 참조) |
| 429 | rate_limited |
Retry-After에 명시된 시간(없으면 몇 초)을 기다린 후 다시 시도하세요; X-RateLimit-Remaining은 이번 분에 남은 요청 수를 보여줍니다 |
| 503 | no_available_provider |
현재 어떤 판매자도 이를 만들 수 없습니다; MartLLM은 이미 다른 판매자를 시도했습니다. 메시지에 현재 작동하는 동일한 종류의 모델 이름이 명시됩니다. |