> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Importar uma imagem de um URL de objeto > Criar uma imagem na conta da plataforma requer um principal atuando nessa conta com `compute:CreateImage`. Registra uma imagem para importação de um URL de objeto pré-assinado — nenhum byte de imagem flui por essa API. Faça o upload do seu disco para qualquer bucket que você controle (nosso armazenamento de objetos, AWS S3, MinIO, …) usando um cliente S3 robusto de várias partes e, em seguida, passe um URL GET pré-assinado como `source_url`. A importação é executada em segundo plano: a resposta é 202 com status=importing, e um worker busca a URL, converte-a para a base bruta (qcow2 / raw / vmdk / vhd / vhdx / vdi são aceitos) e importa-a para o armazenamento regional. A linha vira para ativo (ou erro, com falhas ativas) quando termina — consulte GET /v1/images/{image_id} para o status. Um nome se comporta como uma tag móvel: por padrão, a nova imagem se torna a versão "atual" para o seu (nome, arquitetura), então lançamentos futuros desse nome inicializam os novos bits. Versões mais antigas permanecem inicializáveis por id e por `name:version`. Passe `current: false` para estagiar uma versão sem trocar, então promova-a mais tarde com PATCH /v1/images/{image_id} (current=true). `version` identifica a compilação dentro do nome e deve ser único lá; omita-o e o servidor carimba um timestamp UTC. Publicar duas vezes com o mesmo nome e a mesma versão é um erro 409, não uma segunda compilação anônima. Ação primária do IAM: **`compute:CreateImage`**. Criar uma imagem na conta da plataforma requer um principal atuando nessa conta com `compute:CreateImage`. Consulte [permissões de computação](/pt/compute/permissions) para obter exemplos de políticas. ## OpenAPI ````yaml /pt/api-reference/specs/compute.yaml post /v1/images openapi: 3.0.3 info: title: API de Basaltic Compute version: 1.0.0 description: > Instâncias de máquina virtual e as imagens, os tipos e os pools de instâncias a partir dos quais elas são criadas. Abrange todo o ciclo de vida da instância: iniciar, parar, reiniciar, redimensionar e reinstalar. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://compute.{region}.basaltic.sh description: Endpoint de API regional variables: region: default: sa-saopaulo-1 description: Código de região security: - BearerAuth: [] paths: /v1/images: post: tags: - Images summary: Importar uma imagem de um URL de objeto description: > Criar uma imagem na conta da plataforma requer um principal atuando nessa conta com `compute:CreateImage`. Registra uma imagem para importação de um URL de objeto pré-assinado — nenhum byte de imagem flui por essa API. Faça o upload do seu disco para qualquer bucket que você controle (nosso armazenamento de objetos, AWS S3, MinIO, …) usando um cliente S3 robusto de várias partes e, em seguida, passe um URL GET pré-assinado como `source_url`. A importação é executada em segundo plano: a resposta é 202 com status=importing, e um worker busca a URL, converte-a para a base bruta (qcow2 / raw / vmdk / vhd / vhdx / vdi são aceitos) e importa-a para o armazenamento regional. A linha vira para ativo (ou erro, com falhas ativas) quando termina — consulte GET /v1/images/{image_id} para o status. Um nome se comporta como uma tag móvel: por padrão, a nova imagem se torna a versão "atual" para o seu (nome, arquitetura), então lançamentos futuros desse nome inicializam os novos bits. Versões mais antigas permanecem inicializáveis por id e por `name:version`. Passe `current: false` para estagiar uma versão sem trocar, então promova-a mais tarde com PATCH /v1/images/{image_id} (current=true). `version` identifica a compilação dentro do nome e deve ser único lá; omita-o e o servidor carimba um timestamp UTC. Publicar duas vezes com o mesmo nome e a mesma versão é um erro 409, não uma segunda compilação anônima. operationId: createImage parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImageCreateRequest' responses: '202': description: Imagem registada para importação content: application/json: schema: $ref: '#/components/schemas/ImageResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' security: - BearerAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Chave opcional gerada pelo cliente que torna uma criação segura para reprodução. A reintentar uma solicitação com a mesma chave retorna o resultado original literalmente em vez de criar um recurso duplicado. A reutilização de uma chave com um corpo de solicitação diferente é rejeitada (422); uma solicitação cuja chave ainda está sendo processada retorna 409. Os registros são honrados por 24 horas. Use um UUID ou token exclusivo semelhante. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 schemas: ImageCreateRequest: type: object additionalProperties: false required: - name - source_url properties: name: type: string description: >- Nome de imagem imutável (ex. debian-13) cujo ponteiro para a versão atual pode ser movido; a nova imagem se torna sua versão atual. Os nomes são compartilhados entre as compilações de uma tag — uma compilação é identificada pelo proprietário, nome, arquitetura e versão. Os nomes de recursos não devem começar com o prefixo literal crn: ou ser UUIDs (formas canônicas, compactas, entre colchetes ou urn:uuid:, em qualquer caso). example: debian-13 source_url: type: string description: > URL de GET https pré-signado para o disco em um armazenamento de objetos que você controla. Obtido uma vez pelo worker de importação (que rejeita destinos privados/localizados em link). O worker detecta qcow2, raw, vmdk, vhd, vhdx ou vdi e converte-o para armazenamento raw. Fontes e imagens ilegíveis ou não suportadas que declaram arquivos de backup falham assíncrona com erro de status e uma falha de conversão ativa. Não retidos após a importação. example: https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=... description: type: string example: Debian 13 (Trixie) os: type: string enum: - almalinux - alpine - arch - centos - debian - fedora - opensuse - rhel - rocky - ubuntu - linux default: linux description: >- Distribuição de sistema operacional. Use linux para outra distribuição Linux ou genérica; os_version especifica a versão separadamente. example: debian os_version: type: string example: '13' architecture: type: string enum: - amd64 default: amd64 description: >- Arquitetura da CPU da imagem de origem. Apenas amd64 (x86-64) é suportado. example: amd64 version: type: string description: > Identifica esta compilação dentro de `name`, e deve ser exclusivo lá — republicar uma versão que uma tag já carrega é um 409. Omita-o e o servidor carimba um timestamp UTC, então cada compilação é endereçável como `name:version`, independentemente de você tê-la rotulado ou não. example: '20260807' current: type: boolean default: true description: >- Torne esta a versão atual para o seu (nome, arquitetura) uma vez ativo. example: true eol_date: type: string format: date description: > O dia em que esta versão para de receber atualizações de segurança gratuitas. Se você omitir, a imagem herdará a data da versão atual do nome, então a republicação de uma tag não pode silenciosamente parar de rastrear seu lançamento. example: '2026-08-31' min_disk_gb: type: integer minimum: 0 maximum: 16384 example: 10 min_ram_mb: type: integer minimum: 0 example: 1024 tags: $ref: '#/components/schemas/Tags' attributes: type: object additionalProperties: type: string ImageResponse: type: object properties: image: $ref: '#/components/schemas/Image' required: - image Tags: type: object additionalProperties: type: string example: environment: production team: backend Image: type: object properties: id: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 crn: type: string example: >- crn:compute:sa-saopaulo-1:my-account:image/ubuntu-24.04/architecture/amd64/version/20260901 name: description: >- Os nomes de recursos não devem começar com o prefixo literal crn: ou ser UUIDs (formas canônicas, compactas, entre colchetes ou urn:uuid:, em qualquer caso). type: string example: ubuntu-24.04 description: type: string example: Ubuntu 24.04 LTS (Noble Numbat) os: type: string example: ubuntu os_version: type: string example: '24.04' architecture: type: string example: amd64 version: type: string description: > A identidade da compilação dentro de seu nome. Único lá: um nome é uma tag móvel, então não pode ser também o que diz duas construções separadas. Carimbado como um timestamp UTC quando o carregador não escolheu um. example: '20260807' is_current: type: boolean description: > Se esta é a versão resolve-by-name retorna para o seu (nome, arquitetura) — i.e. o alvo de tag atual do nome. example: true eol_date: type: string format: date description: > O dia em que a versão do SO desta imagem para de receber atualizações de segurança gratuitas para uma instalação padrão. Ausente quando ninguém registrou um — o que significa desconhecido, não "suportado indefinidamente". As imagens da plataforma são retiradas do catálogo após um período de carência após essa data. Eles permanecem inicializáveis por id até então, e a data é publicada bem antes para que você possa planejar a mudança. example: '2026-08-31' size_bytes: type: integer format: int64 example: 2361393152 min_disk_gb: type: integer minimum: 0 maximum: 16384 example: 10 min_ram_mb: type: integer minimum: 0 example: 1024 status: type: string enum: - pending - importing - active - error - deleting - withdrawn description: >- Erro exatamente enquanto uma falha de erro ativo existe; o progresso de importação e exclusão permanecem independentemente retentáveis. example: active withdrawal_reason: type: string description: > Por que esta imagem foi retirada. Presente para imagens retiradas, incluindo aquelas com uma falha de erro independente: end_of_life para retirada de lançamento de plataforma (veja eol_date), ou legado para uma retirada migrada cuja razão original é desconhecida. As imagens retiradas retêm seus dados, mas não podem ser lançadas. example: end_of_life deletion_retention: type: object readOnly: true description: > Apresentar em respostas de lista de proprietários/detalhes enquanto a exclusão de imagem está esperando por referências de instância existente, reserva de origem ou pool de instâncias. As contagens incluem todas as contas de referência sem divulgar suas identidades. Os dados de backup permanecem intactos; a limpeza retoma quando as referências desaparecem. Falhas independentes ainda podem definir o status para erro. required: - reason - instances - instance_pools properties: reason: type: string enum: - in_use instances: type: integer minimum: 0 instance_pools: type: integer minimum: 0 faults: type: array readOnly: true description: >- Falhas ativas, mais recentes primeiro. Vazio para uma imagem saudável. As falhas de erro definem o status como erro sem desabilitar uma reintentância de importação ou limpeza elegível. items: $ref: '#/components/schemas/Fault' tags: $ref: '#/components/schemas/Tags' attributes: type: object additionalProperties: type: string created_at: type: string format: date-time example: '2026-01-15T09:30:00Z' updated_at: type: string format: date-time example: '2026-01-15T09:30:00Z' required: - id - crn - name - version - architecture - status - faults - created_at - updated_at Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Código de erro identificando o tipo de erro example: INVALID_INPUT message: type: string description: Mensagem de erro legível pelo ser humano example: Invalid request parameters params: type: object additionalProperties: true description: >- Valores não sensíveis opcionais para interpolação de erros localizados, codificados por código de erro. Nunca presente para erros de servidor. example: instances: 2 pools: 0 request_id: type: string format: uuid description: Solicitar ID para depuração example: 550e8400-e29b-41d4-a716-446655440000 Fault: type: object required: - code - severity - message - details - first_at - last_at - occurrences properties: code: type: string description: >- Código estável legível por máquina pertencente à operação de relatório. example: BACKUP_FAILED severity: type: string enum: - error - warning message: type: string example: Backup upload failed. details: type: object nullable: true additionalProperties: true description: >- Contexto estruturado; cadeias de caracteres legadas são preservadas em legacy_text. first_at: type: string format: date-time description: Primeira observação nesta série de ocorrências ativas. last_at: type: string format: date-time description: Última observação nesta série de ocorrências ativas. occurrences: type: integer minimum: 1 example: 1 responses: BadRequest: description: Parâmetros de solicitação inválidos content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Autenticação necessária ou token inválido content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Permissões insuficientes content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 Conflict: description: Conflito de recursos (por exemplo, já existe, estado inválido) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CONFLICT message: Resource with this name already exists request_id: 550e8400-e29b-41d4-a716-446655440000 UnprocessableEntity: description: > A solicitação está bem formada, mas não pode ser processada conforme enviada. Nas operações que aceitam `Idempotency-Key` este é o caso de reutilização de chave: a chave foi vista pela primeira vez com uma carga de solicitação diferente, então reproduzir o resultado armazenado responderia a uma pergunta que o chamador não fez. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IDEMPOTENCY_KEY_REUSED message: >- This Idempotency-Key was already used with a different request payload request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >+ Um token bearer OAuth 2.0, enviado como `Authorization: Bearer `. Esta é a forma recomendada de autenticação. Obtenha o token trocando o par de chaves de acesso de uma conta de serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`. Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis com OAuth podem obter e renovar o token para você. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso também serve como credencial AWS SigV4 para o endpoint de objetos compatível com S3, que aceita somente esse método de autenticação. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.