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 una imagen desde una URL de objeto
Crear una imagen en la cuenta de la plataforma requiere que un principal actúe en esa cuenta con compute:CreateImage.
Registra una imagen para importar desde una URL de objeto prefirmada; no se transmiten bytes de imagen a través de esta API. Cargue su disco a cualquier bucket que controle (nuestro almacén de objetos, AWS S3, MinIO, …) utilizando un cliente S3 multiparte robusto, luego pase una URL GET prefirmada como source_url.
La importación se ejecuta en segundo plano: la respuesta es 202 con status=importing, y un worker obtiene la URL, la convierte a la base raw (se aceptan qcow2 / raw / vmdk / vhd / vhdx / vdi) e importa en el almacenamiento regional. La fila cambia a activa (o error, con fallos activos) una vez que termina — consulta GET /v1/images/ para el estado.
Un nombre se comporta como una etiqueta móvil: por defecto la nueva imagen se convierte en la versión “actual” para su (nombre, arquitectura), por lo que los lanzamientos futuros de ese nombre arrancarán los nuevos bits. Las versiones más antiguas permanecen arrancables por id y por name:version. Pasa current: false para poner en espera una versión sin cambiar, luego promuévala más tarde con PATCH /v1/images/ (current=true).
version identifica la compilación dentro del nombre y debe ser única allí; omítalo y el servidor marcará una marca de tiempo UTC. Publicar dos veces con un mismo nombre y la misma versión es un error 409, no una segunda compilación 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. Crear una imagen en la cuenta de la plataforma requiere que un principal actúe en esa cuenta con compute:CreateImage. Consulte permisos de computación para obtener ejemplos de directivas.Autorizaciones
Un token bearer de OAuth 2.0, enviado como Authorization: Bearer <token>. Esta es la forma recomendada de autenticación.
Obtén el token intercambiando el par de claves de acceso de una cuenta de servicio en POST /v1/oauth/token con grant_type=client_credentials. Es el flujo estándar de credenciales de cliente; las bibliotecas compatibles con OAuth pueden obtener y renovar el token por ti.
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
Los tokens duran una hora por defecto. El mismo par de claves de acceso también sirve como credencial AWS SigV4 para el endpoint de objetos compatible con S3, que solo acepta ese método de autenticación.
Encabezados
Clave opcional generada por el cliente que hace que una creación sea segura para la reproducción. Al volver a intentar una solicitud con la misma clave, se devuelve el resultado original literalmente en lugar de crear un recurso duplicado. Se rechaza la reutilización de una clave con un cuerpo de solicitud diferente (422); una solicitud cuya clave todavía se está procesando devuelve 409. Los registros se mantienen durante 24 horas. Usa un UUID o un token único similar.
255Cuerpo
Nombre de imagen inmutable (p. ej. debian-13) cuyo puntero a la versión actual se puede mover; la nueva imagen se convierte en su versión actual. Los nombres se comparten entre las compilaciones de una etiqueta: una compilación se identifica por el propietario, el nombre, la arquitectura y la versión. Los nombres de los recursos no deben comenzar con el prefijo literal crn: ni ser UUID (en cualquier caso, en las formas canónica, compacta, entre corchetes o urn:uuid:).
"debian-13"
URL de obtención https prefirmada al disco en un almacén de objetos que controla. Obtenido una vez por el trabajador de importación (que rechaza los destinos privados/locales de enlace). El worker detecta qcow2, raw, vmdk, vhd, vhdx o vdi y lo convierte en almacenamiento raw. Las fuentes e imágenes ilegibles o no compatibles que declaran archivos de respaldo fallan de forma asíncrona con un error de estado y un error de conversión activa. No se conservan después de la importación.
"https://bucket.s3.example.com/debian-13.qcow2?X-Amz-Signature=..."
"Debian 13 (Trixie)"
Distribución de sistemas operativos. Use linux para otra distribución de Linux o genérica; os_version especifica la versión por separado.
almalinux, alpine, arch, centos, debian, fedora, opensuse, rhel, rocky, ubuntu, linux "debian"
"13"
Arquitectura de CPU de la imagen fuente. Solo se soporta amd64 (x86-64).
amd64 "amd64"
Identifica esta compilación dentro de name, y debe ser única allí — volver a publicar una versión que una etiqueta ya lleva es un 409. Si se omite, el servidor marcará la fecha y hora UTC, de modo que cada compilación sea direccionable como name:version, independientemente de si la ha etiquetado o no.
"20260807"
Hacer que esta sea la versión actual para su (nombre, arquitectura) una vez activa.
true
El día en que esta versión deje de recibir actualizaciones de seguridad gratuitas. Si se omite, la imagen hereda la fecha de la versión actual del nombre, por lo que volver a publicar una etiqueta no puede detener silenciosamente el seguimiento de su lanzamiento.
"2026-08-31"
0 <= x <= 1638410
x >= 01024
Show child attributes
Show child attributes
{
"environment": "production",
"team": "backend"
}
Show child attributes
Show child attributes
Respuesta
Imagen registrada para importación
Show child attributes
Show child attributes