---
title: "Initiate Image Build"
method: POST
path: "/api/v1/images/build"
tags: ["Images"]
---

# Initiate Image Build

`POST /api/v1/images/build`

Initiate an image build process.

Returns a presigned URL to upload the build context (tar.gz file).
After uploading, call /images/build/{build_id}/start to begin the build.

## Request body

- BuildImageRequest — Request model for building or transferring an image.
  - `image_name` string, nullable — Image name (e.g., 'myapp'). Required for build-context builds; optional for transfers.
  - `image_tag` string, nullable — Image tag (e.g., 'v1.0.0'). Required for build-context builds; optional for transfers.
  - `dockerfile_path` string — Path to Dockerfile within build context
  - `sourceImage` string, nullable — Existing public image reference, or comma-separated image references, to transfer instead of uploading a build context
  - `platform` 'linux/amd64' | 'linux/arm64' — Target platform (linux/amd64 or linux/arm64)
  - `teamId` string, nullable — Team ID if building image in team context
  - `visibility` 'INHERIT' | 'PRIVATE' | 'PUBLIC'
  - `ownerScope` 'platform', nullable — Set to 'platform' to build an org-less platform image. Public Docker Hub source transfers are promoted to platform scope automatically; other platform builds remain admin-only. Platform images are PUBLIC and cannot set teamId.

## Response `201`

Successful Response

- union
  - BuildImageResponse — Response model for initiating image build.
    - `build_id` string, required — Build ID for tracking
    - `buildIds` string[] — Build IDs for this request. Multiple IDs are returned for comma-separated transfers.
    - `upload_url` string, nullable — Presigned URL to upload build context (tar.gz)
    - `expires_in` integer, nullable — URL validity in seconds
    - `fullImagePath` string, required — User-facing Prime image reference, preferring owner slug when available
    - `visibility` 'PRIVATE' | 'PUBLIC'
  - BulkImageTransferResponse — Response for comma-separated image transfers. Each source is processed independently: successful items are queued and failed items are returned for the client to retry or fix.
    - `results` TransferImageResult[]
      - `sourceImage` string, required
      - `success` boolean, required
      - `buildId` string, nullable
      - `fullImagePath` string, nullable
      - `visibility` 'PRIVATE' | 'PUBLIC'
      - `error` string, nullable
      - `retryable` boolean
    - `failed` TransferImageResult[]
      - `sourceImage` string, required
      - `success` boolean, required
      - `buildId` string, nullable
      - `fullImagePath` string, nullable
      - `visibility` 'PRIVATE' | 'PUBLIC'
      - `error` string, nullable
      - `retryable` boolean

## Other responses

- `401` — Authorization failed
- `422` — Invalid request data

---

[API](https://skmtc.net/primeintellect/apis/pi-api.md) · [All operations](https://skmtc.net/primeintellect/apis/pi-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/primeintellect/pi-api/revisions/60efc9b3ff2a/schema)