> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar imagem

> Cria uma imagem Docker personalizada a partir de um contexto de build (ZIP) ou de um repositório do GitHub, e inicia o build dela.

Disponível nos planos **Enterprise 28, Enterprise 30 e Enterprise 32**. A requisição é `multipart/form-data`. O contexto de build tem **duas fontes mutuamente exclusivas**: `file`, ou `github_repository` (o branch é opcional). Ele precisa ter um arquivo chamado exatamente `Dockerfile` na sua raiz; uma pasta única que o envolva é aceita. Arquivos `.env*` são removidos do contexto e o `.dockerignore` é respeitado. O `Dockerfile` nunca é reescrito. Veja [Imagens Docker personalizadas](https://docs.vertracloud.app/pt-br/guides/custom-docker-images.md) para as regras.

Exige o escopo `images:write` quando chamada com uma chave de API. Verifique antes um `Dockerfile` com [Verificar Dockerfile](https://docs.vertracloud.app/pt-br/api-reference/endpoint/images/check.md).

**name** `string` *required*

O nome da imagem: de 1 a 50 caracteres, único entre as suas imagens.

**description** `string`

Descrição opcional em texto livre, de até 128 caracteres. Um valor vazio significa sem descrição. Você pode alterá-la depois com [Atualizar imagem](https://docs.vertracloud.app/pt-br/api-reference/endpoint/images/update.md).

**file** `file`

O contexto de build: um arquivo ZIP, de até 100 MB. Ausente quando a fonte é o GitHub.

**github\_repository** `string`

Alternativa a `file`: o repositório do GitHub a partir do qual fazer o build, no formato `owner/name`.

* Um repositório de uma das suas instalações do GitHub App fica **vinculado** à imagem: um push para o branch refaz o build dela.
* Um repositório **público** fora das suas instalações é construído **uma vez**, sem vínculo (`github` é `null` na resposta). Para ter rebuilds automáticos, instale o GitHub App no repositório e chame [Vincular imagem ao GitHub](https://docs.vertracloud.app/pt-br/api-reference/endpoint/images/github-link.md).
* Um repositório privado ou inexistente fora das suas instalações falha com `INSTALLATION_NOT_FOUND`.

**github\_branch** `string`

O branch de `github_repository` a partir do qual fazer o build. Opcional: sem ele, usa-se o branch padrão do repositório (`main`, `master` ou o que o repositório definir). Quando o repositório está vinculado, este também é o branch cujos pushes refazem o build da imagem. Um branch que não existe falha com `INSTALLATION_NOT_FOUND`.

**workspace\_id** `string`

O workspace que será dono da imagem.

### Resposta

**response** `object`

A imagem. A criação é assíncrona: a resposta é `202 Accepted` com `status: "building"`. Acompanhe com [Obter imagem](https://docs.vertracloud.app/pt-br/api-reference/endpoint/images/get.md) ou com os [logs do build](https://docs.vertracloud.app/pt-br/api-reference/endpoint/images/logs.md) até que `status` seja `success` ou `failed`.

**Mostrar objeto**

**id** `string`

O ID da imagem.

**name** `string`

O nome da imagem.

**description** `string | null`

A descrição da imagem (texto livre, de até 128 caracteres), ou `null` quando não tem uma.

**owner** `string`

`account` para as suas imagens, `system` para imagens fornecidas pela plataforma (estas não podem ser alteradas nem excluídas).

**status** `string`

Estado do build mais recente: `building`, `success` ou `failed`. Um rebuild que falha não altera a versão atual: as aplicações continuam rodando a última versão boa.

**error** `string | null`

Motivo legível do build mais recente que falhou, ou `null`.

**digest** `string | null`

Digest (`sha256:...`) da versão atual, ou `null` enquanto nenhum build teve sucesso.

**uncompressed\_bytes** `integer | null`

Tamanho da versão atual, descompactada, em bytes.

**layer\_count** `integer | null`

Número de camadas da versão atual.

**apps** `object[]`

As aplicações criadas a partir desta imagem. Cada uma tem `id`, `name`, `version_id` (a versão da imagem que ela executa, ou `null`) e `outdated` (`true` quando a imagem tem uma versão mais nova; a aplicação passa para ela no próximo restart ou deploy que você pedir).

**github** `object | null`

O repositório e o branch do GitHub vinculados (`repository` como `owner/name`, `branch`), ou `null` quando a imagem não está vinculada, como quando foi construída uma vez a partir de um repositório público.

**current\_version\_id** `string | null`

A versão atual da imagem, ou `null` enquanto nenhum build teve sucesso.

**created\_at** `string`

Quando a imagem foi criada.

**updated\_at** `string`

Quando a imagem foi atualizada pela última vez.

```json Response theme={null}
{
  "response": {
    "id": "img-abc123def456",
    "name": "my-api",
    "description": null,
    "owner": "account",
    "status": "building",
    "error": null,
    "digest": null,
    "uncompressed_bytes": null,
    "layer_count": null,
    "apps": [],
    "github": null,
    "current_version_id": null,
    "created_at": "2026-10-23T14:02:00Z",
    "updated_at": "2026-10-23T14:02:00Z"
  }
}
```

### Respostas de erro

**code** `string`

O código de erro que indica o motivo da falha. Valores possíveis:

* `API_KEY_SCOPE_DENIED`: A chave de API não tem o escopo exigido (`403`).
* `VALIDATION_ERROR`: O body multipart falhou na validação, por exemplo um `github_repository` que não está no formato `owner/name` (`400`).
* `PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES`: O plano não inclui imagens Docker personalizadas (`403`).
* `MAX_IMAGES_REACHED`: Foi atingido o limite de 20 imagens do plano; imagens em qualquer estado contam (`403`).
* `DOCKERFILE_NOT_FOUND`: Não existe um arquivo chamado exatamente `Dockerfile` na raiz do contexto (`400`).
* `DOCKERFILE_REFUSED`: O `Dockerfile` tem uma instrução recusada; `details` lista os achados (`400`). Veja [Verificar Dockerfile](https://docs.vertracloud.app/pt-br/api-reference/endpoint/images/check.md).
* `IMAGE_CONTEXT_TOO_LARGE`: O contexto de build passou de um limite: mais de 100 MB compactado, mais de 512 MB descompactado, mais de 50.000 entradas, ou um `Dockerfile` maior que 1 MB (`413`).
* `IMAGE_BUILDER_UNAVAILABLE`: Nenhum host pode fazer build de imagens agora; tente novamente mais tarde (`503`).
* `INSTALLATION_NOT_FOUND`: O repositório é privado ou não existe, e não está nas suas instalações do GitHub App; ou o branch não existe (`404`).
* `REPO_ALREADY_LINKED`: O repositório já está vinculado a outra imagem ou aplicação (`409`).
* `FETCH_ZIP_ERROR`: Não foi possível acessar o GitHub, ou ele estava limitando requisições enquanto o repositório era buscado (`502`). Tente novamente em alguns minutos.
* `INTERNAL_SERVER_ERROR`: Falha inesperada (`500`).

```json Error Response theme={null}
{
  "code": "DOCKERFILE_REFUSED",
  "details": [{ "code": "run_network_host", "line": 7 }]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.