curl --request POST \
--url https://compute.{region}.basaltic.sh/v1/images \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "debian-13",
"source_url": "https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...",
"description": "Debian 13 (Trixie)",
"os": "debian",
"os_version": "13",
"architecture": "amd64",
"version": "20260807",
"current": true,
"eol_date": "2026-08-31",
"min_disk_gb": 10,
"min_ram_mb": 1024,
"tags": {
"environment": "production",
"team": "backend"
},
"attributes": {}
}
'import requests
url = "https://compute.{region}.basaltic.sh/v1/images"
payload = {
"name": "debian-13",
"source_url": "https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...",
"description": "Debian 13 (Trixie)",
"os": "debian",
"os_version": "13",
"architecture": "amd64",
"version": "20260807",
"current": True,
"eol_date": "2026-08-31",
"min_disk_gb": 10,
"min_ram_mb": 1024,
"tags": {
"environment": "production",
"team": "backend"
},
"attributes": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'debian-13',
source_url: 'https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...',
description: 'Debian 13 (Trixie)',
os: 'debian',
os_version: '13',
architecture: 'amd64',
version: '20260807',
current: true,
eol_date: '2026-08-31',
min_disk_gb: 10,
min_ram_mb: 1024,
tags: {environment: 'production', team: 'backend'},
attributes: {}
})
};
fetch('https://compute.{region}.basaltic.sh/v1/images', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://compute.{region}.basaltic.sh/v1/images",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'debian-13',
'source_url' => 'https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...',
'description' => 'Debian 13 (Trixie)',
'os' => 'debian',
'os_version' => '13',
'architecture' => 'amd64',
'version' => '20260807',
'current' => true,
'eol_date' => '2026-08-31',
'min_disk_gb' => 10,
'min_ram_mb' => 1024,
'tags' => [
'environment' => 'production',
'team' => 'backend'
],
'attributes' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://compute.{region}.basaltic.sh/v1/images"
payload := strings.NewReader("{\n \"name\": \"debian-13\",\n \"source_url\": \"https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...\",\n \"description\": \"Debian 13 (Trixie)\",\n \"os\": \"debian\",\n \"os_version\": \"13\",\n \"architecture\": \"amd64\",\n \"version\": \"20260807\",\n \"current\": true,\n \"eol_date\": \"2026-08-31\",\n \"min_disk_gb\": 10,\n \"min_ram_mb\": 1024,\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n },\n \"attributes\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://compute.{region}.basaltic.sh/v1/images")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"debian-13\",\n \"source_url\": \"https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...\",\n \"description\": \"Debian 13 (Trixie)\",\n \"os\": \"debian\",\n \"os_version\": \"13\",\n \"architecture\": \"amd64\",\n \"version\": \"20260807\",\n \"current\": true,\n \"eol_date\": \"2026-08-31\",\n \"min_disk_gb\": 10,\n \"min_ram_mb\": 1024,\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n },\n \"attributes\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://compute.{region}.basaltic.sh/v1/images")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"debian-13\",\n \"source_url\": \"https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...\",\n \"description\": \"Debian 13 (Trixie)\",\n \"os\": \"debian\",\n \"os_version\": \"13\",\n \"architecture\": \"amd64\",\n \"version\": \"20260807\",\n \"current\": true,\n \"eol_date\": \"2026-08-31\",\n \"min_disk_gb\": 10,\n \"min_ram_mb\": 1024,\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n },\n \"attributes\": {}\n}"
response = http.request(request)
puts response.read_body{
"image": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"crn": "crn:compute:sa-saopaulo-1:my-account:image/ubuntu-24.04/architecture/amd64/version/20260901",
"name": "ubuntu-24.04",
"architecture": "amd64",
"version": "20260807",
"status": "active",
"faults": [
{
"code": "BACKUP_FAILED",
"severity": "error",
"message": "Backup upload failed.",
"details": {},
"first_at": "2023-11-07T05:31:56Z",
"last_at": "2023-11-07T05:31:56Z",
"occurrences": 1
}
],
"created_at": "2026-01-15T09:30:00Z",
"updated_at": "2026-01-15T09:30:00Z",
"description": "Ubuntu 24.04 LTS (Noble Numbat)",
"os": "ubuntu",
"os_version": "24.04",
"is_current": true,
"eol_date": "2026-08-31",
"size_bytes": 2361393152,
"min_disk_gb": 10,
"min_ram_mb": 1024,
"withdrawal_reason": "end_of_life",
"deletion_retention": {
"reason": "in_use",
"instances": 1,
"instance_pools": 1
},
"tags": {
"environment": "production",
"team": "backend"
},
"attributes": {}
}
}{
"error": {
"code": "INVALID_INPUT",
"message": "Invalid request parameters",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "ACCESS_DENIED",
"message": "You don't have permission to perform this action",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "CONFLICT",
"message": "Resource with this name already exists",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "This Idempotency-Key was already used with a different request payload",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}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/ 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/ (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.
curl --request POST \
--url https://compute.{region}.basaltic.sh/v1/images \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "debian-13",
"source_url": "https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...",
"description": "Debian 13 (Trixie)",
"os": "debian",
"os_version": "13",
"architecture": "amd64",
"version": "20260807",
"current": true,
"eol_date": "2026-08-31",
"min_disk_gb": 10,
"min_ram_mb": 1024,
"tags": {
"environment": "production",
"team": "backend"
},
"attributes": {}
}
'import requests
url = "https://compute.{region}.basaltic.sh/v1/images"
payload = {
"name": "debian-13",
"source_url": "https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...",
"description": "Debian 13 (Trixie)",
"os": "debian",
"os_version": "13",
"architecture": "amd64",
"version": "20260807",
"current": True,
"eol_date": "2026-08-31",
"min_disk_gb": 10,
"min_ram_mb": 1024,
"tags": {
"environment": "production",
"team": "backend"
},
"attributes": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'debian-13',
source_url: 'https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...',
description: 'Debian 13 (Trixie)',
os: 'debian',
os_version: '13',
architecture: 'amd64',
version: '20260807',
current: true,
eol_date: '2026-08-31',
min_disk_gb: 10,
min_ram_mb: 1024,
tags: {environment: 'production', team: 'backend'},
attributes: {}
})
};
fetch('https://compute.{region}.basaltic.sh/v1/images', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://compute.{region}.basaltic.sh/v1/images",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'debian-13',
'source_url' => 'https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...',
'description' => 'Debian 13 (Trixie)',
'os' => 'debian',
'os_version' => '13',
'architecture' => 'amd64',
'version' => '20260807',
'current' => true,
'eol_date' => '2026-08-31',
'min_disk_gb' => 10,
'min_ram_mb' => 1024,
'tags' => [
'environment' => 'production',
'team' => 'backend'
],
'attributes' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://compute.{region}.basaltic.sh/v1/images"
payload := strings.NewReader("{\n \"name\": \"debian-13\",\n \"source_url\": \"https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...\",\n \"description\": \"Debian 13 (Trixie)\",\n \"os\": \"debian\",\n \"os_version\": \"13\",\n \"architecture\": \"amd64\",\n \"version\": \"20260807\",\n \"current\": true,\n \"eol_date\": \"2026-08-31\",\n \"min_disk_gb\": 10,\n \"min_ram_mb\": 1024,\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n },\n \"attributes\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://compute.{region}.basaltic.sh/v1/images")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"debian-13\",\n \"source_url\": \"https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...\",\n \"description\": \"Debian 13 (Trixie)\",\n \"os\": \"debian\",\n \"os_version\": \"13\",\n \"architecture\": \"amd64\",\n \"version\": \"20260807\",\n \"current\": true,\n \"eol_date\": \"2026-08-31\",\n \"min_disk_gb\": 10,\n \"min_ram_mb\": 1024,\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n },\n \"attributes\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://compute.{region}.basaltic.sh/v1/images")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"debian-13\",\n \"source_url\": \"https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=...\",\n \"description\": \"Debian 13 (Trixie)\",\n \"os\": \"debian\",\n \"os_version\": \"13\",\n \"architecture\": \"amd64\",\n \"version\": \"20260807\",\n \"current\": true,\n \"eol_date\": \"2026-08-31\",\n \"min_disk_gb\": 10,\n \"min_ram_mb\": 1024,\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n },\n \"attributes\": {}\n}"
response = http.request(request)
puts response.read_body{
"image": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"crn": "crn:compute:sa-saopaulo-1:my-account:image/ubuntu-24.04/architecture/amd64/version/20260901",
"name": "ubuntu-24.04",
"architecture": "amd64",
"version": "20260807",
"status": "active",
"faults": [
{
"code": "BACKUP_FAILED",
"severity": "error",
"message": "Backup upload failed.",
"details": {},
"first_at": "2023-11-07T05:31:56Z",
"last_at": "2023-11-07T05:31:56Z",
"occurrences": 1
}
],
"created_at": "2026-01-15T09:30:00Z",
"updated_at": "2026-01-15T09:30:00Z",
"description": "Ubuntu 24.04 LTS (Noble Numbat)",
"os": "ubuntu",
"os_version": "24.04",
"is_current": true,
"eol_date": "2026-08-31",
"size_bytes": 2361393152,
"min_disk_gb": 10,
"min_ram_mb": 1024,
"withdrawal_reason": "end_of_life",
"deletion_retention": {
"reason": "in_use",
"instances": 1,
"instance_pools": 1
},
"tags": {
"environment": "production",
"team": "backend"
},
"attributes": {}
}
}{
"error": {
"code": "INVALID_INPUT",
"message": "Invalid request parameters",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "ACCESS_DENIED",
"message": "You don't have permission to perform this action",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "CONFLICT",
"message": "Resource with this name already exists",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "This Idempotency-Key was already used with a different request payload",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}compute:CreateImage. Criar uma imagem na conta da plataforma requer um principal atuando nessa conta com compute:CreateImage. Consulte permissões de computação para obter exemplos de políticas.Autorizações
Um token bearer OAuth 2.0, enviado como Authorization: Bearer <token>. 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.
Cabeçalhos
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.
255Corpo
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).
"debian-13"
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.
"https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=..."
"Debian 13 (Trixie)"
Distribuição de sistema operacional. Use linux para outra distribuição Linux ou genérica; os_version especifica a versão separadamente.
almalinux, alpine, arch, centos, debian, fedora, opensuse, rhel, rocky, ubuntu, linux "debian"
"13"
Arquitetura da CPU da imagem de origem. Apenas amd64 (x86-64) é suportado.
amd64 "amd64"
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.
"20260807"
Torne esta a versão atual para o seu (nome, arquitetura) uma vez ativo.
true
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.
"2026-08-31"
0 <= x <= 1638410
x >= 01024
Show child attributes
Show child attributes
{
"environment": "production",
"team": "backend"
}
Show child attributes
Show child attributes
Resposta
Imagem registada para importação
Show child attributes
Show child attributes