Skip to main content
IBM Quantum Platform

Qiskit Runtime API REST

La API REST de Qiskit Runtime le permite ejecutar en unidades de procesamiento cuántico (QPU) utilizando las primitivas de Qiskit Runtime, una interfaz simplificada para la ejecución de circuitos potenciada por técnicas avanzadas de compilación en tiempo de ejecución, supresión de errores y mitigación de errores, así como obtener información sobre las instancias y las QPU a las que tiene acceso.

Gestionar instancias con la API del controlador de recursos de IBM Cloud

Antes de utilizar la API REST de Qiskit Runtime, necesitas una instancia de Qiskit Runtime. Puedes crear y gestionar instancias de dos maneras:

  • Uso de la interfaz de usuario : Crea y gestiona instancias a través de la interfaz de IBM Quantum Platform. Al utilizar la interfaz de usuario, si marcas la casilla «Establecer como límite», instance_limit_seconds se establecerá en el mismo valor que usage_allocation_seconds.
  • Uso de la API : Automatice el aprovisionamiento y la configuración de instancias mediante programación con la API del controlador de recursos de IBM Cloud (distinta de la API REST de Qiskit Runtime ). Utiliza la API si necesitas establecer valores diferentes para el límite de asignación y el límite de uso.

En las siguientes secciones se describe el enfoque de la API para la gestión programática de instancias, incluyendo la configuración de límites de asignación y el acceso al backend.

Parámetros de instancia

Al crear o actualizar una instancia de « Qiskit Runtime » a través de la API del controlador de recursos de « IBM Cloud », puedes configurar los siguientes parámetros en el cuerpo de la solicitud:

  • instance_limit_seconds (opcional): El límite que se va a establecer en la instancia (cadena de caracteres o nulo). En Open Plan, el valor predeterminado es de 10 minutos si no se especifica.
  • usage_allocation_seconds: Tiempo asignado a la instancia (cadena de caracteres o nulo), que utiliza el programador de reparto equitativo para determinar la prioridad de la cola en función del uso de todas las QPU. No se aplica a las instancias de pago por uso.
  • backends: Conjunto de nombres de backend disponibles para esta instancia (matriz de cadenas o ["ANY"]). La configuración predeterminada es ["ANY"] (todos los backends disponibles en el plan). Utiliza [] si no hay servidores de fondo.

Extensiones de instancia

Cuando se recuperan los detalles de una instancia a través de la API del controlador de recursos de IBM Cloud, la respuesta incluye una extensions propiedad con información adicional sobre la instancia:

  • instance_limit_seconds: El límite de tiempo establecido para la instancia (entero o nulo, ≥ 0)
  • usage_allocation_seconds: Tiempo asignado a la instancia (entero o nulo, ≥ 0)
  • backends: La lista de nombres de backends permitidos para esta instancia (matriz obligatoria)

Para obtener información detallada sobre los parámetros y las extensiones, incluidos ejemplos y puntos de conexión de la API, consulta «Uso de las API de la plataform IBM Cloud » para acceder a las instancias.

Utiliza la API REST de Qiskit Runtime

En las siguientes secciones se describe cómo utilizar la API REST de Qiskit Runtime para enviar trabajos y gestionar sesiones. Estas operaciones requieren autenticación y una instancia ya existente.

Autenticación

Debe proporcionar un token de portador IBM Cloud Identity and Access Management (IAM) con cada llamada como encabezado http. Puede generarlo utilizando su clave API desde el Panel de control, cerca de la parte superior para facilitar el acceso. Consulte la API de servicios de identidad de IAM para obtener más información sobre los tokens portadores. Para generar una utilizando la API REST de IAM, puede utilizar la siguiente solicitud curl.

curl -X POST 'https://iam.cloud.ibm.com/identity/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=MY_APIKEY'

Respuesta esperada

{
   "access_token": "<NEW_BEARER_TOKEN>",
   "refresh_token": "not_supported",
   "token_type": "Bearer",
   "expires_in": 3600,
   "expiration": 1473188353,
   "scope": "ibm_openid"
}
¿Qué es una ficha al portador?

Un token al portador es una credencial temporal que caduca al cabo de una hora como máximo. Cuando caduque el token adquirido, deberá generar uno nuevo para seguir llamando a IBM Cloud o a otras API de servicios. Sólo puede realizar acciones permitidas por su nivel de acceso asignado dentro de todas las cuentas.

Utilice la propiedad de respuesta expires_in en la respuesta de la API para identificar el tiempo de validez de su token de acceso específico.

Además, muchas solicitudes a la API REST requieren el nombre de recurso en la nube (CRN) de una instancia en el encabezado de la solicitud. Puede ver las instancias a las que tiene acceso en el panel de control, o seleccionando la página Instancias en el menú superior izquierdo. Cada instancia aparece con su identificador CRN.

A continuación, envíe su token de portador, CRN y IBM -API-Version en cada solicitud dentro de una cabecera Authorization y Service-CRN con este formato:

Authorization: Bearer <YOUR_BEARER_TOKEN>
Service-CRN: <YOUR_INSTANCE_CRN>
IBM-API-Version: <YYYY-MM-DD>

Solicitud de ejemplo:

región eu-de

Si su instancia se encuentra en la región eu-de, utilice en su lugar esta dirección URL: https://eu-de.quantum.cloud.ibm.com/api/v1/backends

curl -X 'GET' \
    'https://quantum.cloud.ibm.com/api/v1/backends' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
    -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
    -H 'IBM-API-Version: 2026-04-15'

Enviar un trabajo

Tenga en cuenta lo siguiente al enviar un trabajo:

  • Utilice la operación crear trabajo para enviar trabajos primitivos.
  • Puede enviar varios circuitos en un solo trabajo como una matriz de OpenQASM cadenas que representan estos circuitos.
  • Especifique la primitiva que desea utilizar con el parámetro program_id . Los valores primitivos disponibles son sampler y estimator.
  • Al enviar un trabajo a una QPU, debe especificar su CRN de instancia de IBM Cloud.
  • Para obtener una lista de los nombres de backend que puede especificar, consulte los backends a los que tiene acceso en la sección Recursos informáticos de IBM Quantum Platform.

Ejemplo de solicitud de creación de un trabajo de estimador con un circuito y un observable:

región eu-de

Si su instancia se encuentra en la región eu-de, utilice en su lugar esta dirección URL: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs

curl -X 'POST' \
  'https://quantum.cloud.ibm.com/api/v1/jobs' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
  -H 'IBM-API-Version: 2026-04-15' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "program_id": "estimator",
  "backend": "ibm_brisbane",
  "params": {
    "pubs": [[
      "OPENQASM 3.0; include \"stdgates.inc\"; bit[1] c; x $0; c[0] = measure $0;", "Z"
    ]],
    "options": {"dynamical_decoupling": {"enable": true}},
    "version": 2,
    "resilience_level": 1
  }
}'

Usar sesiones

Para iniciar una sesión, utilice la operación crear sesión. La respuesta proporciona un "id" que puede enviar con sus trabajos para ejecutarlos como parte de la sesión.

El siguiente ejemplo crea una sesión (sin especificar el modo):

región eu-de

Si su instancia se encuentra en la región eu-de, utilice en su lugar esta dirección URL: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions

curl -X POST \
  'https://quantum.cloud.ibm.com/api/v1/sessions' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
  -H 'IBM-API-Version: 2026-04-15' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "mode": "dedicated",
  "max_ttl": 28800
}'

Obtendrá una respuesta como ésta:

{
  "id": "session_id1"
}

En su próximo trabajo, utilice el identificador de sesión para ejecutar este trabajo como parte de la sesión:

región eu-de

Si su instancia se encuentra en la región eu-de, utilice en su lugar esta dirección URL: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs

curl -X POST \
  'https://quantum.cloud.ibm.com/api/v1/jobs' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
  -H 'IBM-API-Version: 2026-04-15' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "program_id": "sampler",
  "backend": "ibm_brisbane",
  "session_id": "session_id1",
  "params": {
    "pubs": [[
      "OPENQASM 3.0; include \"stdgates.inc\"; bit[1] c; x $0; c[0] = measure $0;"
    ]],
    "options": {},
    "version": 2
  }
}'
¿Le ha resultado útil esta página?
Informe de un error, de una errata o solicite contenido en GitHub.