APIドキュメント
Vectorgramをアプリケーションに組み込みましょう。送信用、ポーリング用、ダウンロード用のエンドポイントが1つずつ。ジョブは設計上、非同期です。ベースURLはhttps://api.vectorgram.ai、認証はAuthorization: Bearer <api_key>です。キーは次のような形式ですvectorgram_sk_live_…。プレフィックスを意図的に省略なく表記しているため、古い.envで見つかったキーも、実際に試さずに特定できます。
新規アカウントでは、API変換を30日間25回無料で利用できます。フル品質、透かしなし。その後は、APIを含むプラン（Pro以上）が必要になり、呼び出しはそのプランの月間枠から消費されます。超過課金はないため、枠を使い切った後の呼び出しには402がリセット日時とともに返ります。GET /v1/accountは、両方の枠とそれぞれの残りを報告します。
クイックスタート
1：APIキーを取得
読み込んでいます…
2：画像を送信
curl -X POST https://api.vectorgram.ai/v1/vectorize \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 8f1b0c2e-0a1d-4f77-9c3a-2b6e5d4c1a90" \
-F "file=@image.png" \
-F "image_type=clipart" \
-F "detail=high" \
-F "gradients=smooth" \
-F "smoothing=strong" \
-F "retention=24h"レスポンスは202 Acceptedで、ジョブはキューに投入された状態です。変換はまだ行われていません。同じリクエストを同じIdempotency-Keyで2回送信すると、2つ目を作る代わりに最初のジョブが返されます。使用済みのキーでファイルや設定を変更するのは409です。
3：ポーリング、またはWebhookで受信
GET /v1/jobs/job_abc123
{
"id": "job_abc123",
"status": "queued",
"progress": 0,
"queue_position": 3,
"mode": "logo",
"retention": "24h",
"megapixels": 2.1,
"created_at": "2026-08-03T10:30:00Z"
}statusはqueued → processing → completed | failed | canceled | expiredのように遷移します。キューに入っている間は、実際のqueue_positionが返ります。でっち上げたカウントダウンではありません。処理中のprogressは、サイズの見積もりから補間された値で、ファイルが実際に存在するようになるまで95%で頭打ちになります。大きな画像には数分かかることもあります。常識的な間隔でポーリングするか、さらに良い方法としてWebhookを登録してください。
4：ダウンロード
{
"id": "job_abc123",
"status": "completed",
"progress": 100,
"download_url": "https://api.vectorgram.ai/v1/jobs/job_abc123/download",
"completed_at": "2026-08-03T10:30:04Z",
"expires_at": "2026-08-04T10:30:04Z"
}download_urlが現れるのは結果が存在するようになってからです。同じベアラートークンが必要で、ファイルは添付としてストリーミングされます。retention=noneの場合、ファイルは提供と同時に削除されます。ダウンロードは一度だけ行ってください。
変換パラメータ
すべてのフィールドは、POST /v1/vectorizeへのmultipart form dataとして送ります。バッジ手動が付いた4つはトレース制御です。Pro、Studio、Agency、Enterpriseで利用できます。FreeとLiteでは、これらは拒否されずに受け入れられた後、既定値へ置き換えられます。そのため、常に送り続けるクライアントでも変換は完了します。得られるのは自動結果というだけです。
必須。変換する画像です。ファイル名ではなくバイト列から判定されます。
画像の種類。既定はautoで、エンジンによる自動分類に任せます。
省略可。svgが唯一の値です。エンジンが書き出すのはSVGで、それを別の形式に変換する処理はありません。EPS、PNG、PDF、DXF、AIは、キューに入れて失敗させるのではなく、400 unsupported_output_formatで拒否されます。
結果の保持期間。既定は24h。noneは最初のダウンロード後に削除します。要求は拒否されず、プランの上限に丸められます。Freeでは要求しても結果を10日間保持することはできません。
自分で決めるグルーピングキー。ジョブにそのまま返され、フィルターとしても使えます。画像1枚につき1リクエストを送ります。一括変換はProから（30ファイル、Studioで50、Agencyで100）。それ未満ではグループに保持できるのは1ファイルだけで、2つ目は400 batch_limit_exceededを返します。
ダッシュボードで一括のファイルが置かれるフォルダの名前。省略可ですがbatch_idが必要です（ない場合は400 invalid_folder_name）。文字数はbatch_idと同じく128文字で、制御文字は使えません。最初に受け入れられたファイルがフォルダ名を決め、以降のファイルが名前を変えることはありません。省略した場合は、作成日を冠した名前が付きます。
領域のマージを経て画像に残る情報の量。既定はhigh。1.3.0以降のエンジンでは最も緩いステップです。1〜100のスライダー値も受け付け、段階に振り分けられます。
グラデーションの処理。既定はsmooth。steppedとautoでは、エンジンのフラットな塗りがそのまま残ります。
角の丸め。既定はstrong。本当の角は鋭さを保ち、ベクター化エンジンが誤って丸めた部分だけが丸まって返ります。0〜100のスライダー値も受け付け、段階に振り分けられます。
エンジンが描くもの。既定はfill。すべての形状が塗りつぶしのアウトラインになります。centerlineは各線の中央に沿って1本の開いたストロークを描き（fill="none"、ストロークの色と幅を指定）、プロッター、レーザー彫刻機、CNCルーター、カッティングマシンがたどるのはこちらで、輪郭を2周する代わりに線1本につき1パスで済みます。線として扱うには太すぎる部分は、塗りつぶし形状のまま残ります。detail、gradients、smoothingは適用されず無視されます。不明な値には400を返します。
シームの閉じ。全プランで有効。既定はtrue。各塗りは隣の下に0.75 px回り込むため、2色の間に細い明るい線が現れません。falseにすると正確な分割になり、形状は重なりなく端から端まで接します（ジオメトリ編集用）。どちらの場合も形状は一切移動しません。centerlineでは無視されます。
エンドポイント
生成されるリファレンス（あらゆるフィールド、あらゆるレスポンス形状）は、サービスが次の場所で公開しているSwagger UIです。/docs/swaggerOpenAPIドキュメントは/v3/api-docsにあります。
Webhook
ジョブは非同期で実行されます。大きなファイルでは数分かかることもあるため、ポーリングの代わりにWebhookを購読してください。エンドポイントはPOST /v1/webhooksで登録します。署名シークレットは作成時に一度だけ返され、その後は二度と表示されません。
POST https://your-app.example/hooks/vectorgram
X-Vectorgram-Event: processing.completed
X-Vectorgram-Signature: sha256=<hmac of the raw body, hex>
{
"id": "evt_9f2c…",
"event": "processing.completed",
"created_at": "2026-08-03T10:30:04Z",
"data": { "job_id": "job_abc123", "status": "completed" }
}署名の検証は、生のリクエストボディからエンドポイントのシークレットでHMAC-SHA256を計算し、定数時間で比較して行います。一致しない場合は未認証のリクエストとして扱ってください。配信は最低1回です。非2xxのレスポンスは指数バックオフで3回再試行されるため、ハンドラはidについてべき等にしてください。エンドポイントは公開アドレスに解決できなければなりません。これは登録時だけでなく、配信時にも再確認されます。
エラー
失敗はJSONとして返ります：{ "error": { "code": "…", "message": "…", "details": { … } } }。読むべきはcodeであり、メッセージではありません。メッセージは言い回しが変わることがあります。