Qiskit Runtime API REST

A API Qiskit Runtime REST permite que você execute em unidades de processamento quântico (QPUs) usando primitivas Qiskit Runtime, uma interface simplificada para execução de circuitos com tecnologia de compilação avançada de tempo de execução, supressão de erros e técnicas de atenuação de erros, além de obter informações sobre instâncias e QPUs às quais você tem acesso.

Gerenciar instâncias com a API do Controlador de Recursos do `IBM Cloud`

Antes de usar a API REST do Qiskit Runtime, você precisa de uma instância do Qiskit Runtime. Você pode criar e gerenciar instâncias de duas maneiras:

Como usar a interface do usuário : Crie e gerencie instâncias por meio da interface IBM Quantum Platform. Ao usar a interface do usuário, se você marcar a caixa de seleção “definir como limite”, instance_limit_seconds será definido com o mesmo valor que usage_allocation_seconds.
Como usar a API : Automatize o provisionamento e a configuração de instâncias programaticamente usando a API do Controlador de Recursos do IBM Cloud (distinta da API REST do Qiskit Runtime ). Use a API se precisar definir valores diferentes para o limite de alocação e o limite de uso.

As seções a seguir descrevem a abordagem da API para o gerenciamento programático de instâncias, incluindo a definição de limites de alocação e o acesso ao backend.

Parâmetros da instância

Ao criar ou atualizar uma instância do Qiskit Runtime por meio da API do Controlador de Recursos do IBM Cloud, é possível configurar os seguintes parâmetros no corpo da solicitação:

instance_limit_seconds (opcional): O limite a ser definido na instância (cadeia de caracteres ou nulo). Para o Open Plan, o valor padrão é de 10 minutos, caso não seja especificado.
usage_allocation_seconds: Tempo alocado para a instância (string ou nulo), utilizado pelo agendador de compartilhamento justo para determinar a prioridade da fila com base na utilização de todas as QPUs. Não se aplica a instâncias do modelo Pay-As-You-Go.
backends: Matriz de nomes de back-end disponíveis para esta instância (matriz de strings ou ["ANY"]). O padrão é ["ANY"] (todos os back-ends disponíveis no plano). Use [] quando não houver backends.

Extensões de instância

Ao recuperar detalhes da instância por meio da API do Controlador de Recursos IBM Cloud, a resposta inclui uma extensions propriedade com informações adicionais sobre a instância:

instance_limit_seconds: O limite de tempo definido para a instância (número inteiro ou nulo, ≥ 0)
usage_allocation_seconds: Tempo alocado para a instância (número inteiro ou nulo, ≥ 0)
backends: A lista de nomes de backends permitidos para esta instância (matriz obrigatória)

Para obter detalhes completos sobre parâmetros e extensões, incluindo exemplos e pontos de extremidade da API, consulte “Usar as APIs da plataform IBM Cloud para acessar instâncias ”.

Use a API REST do Qiskit Runtime

As seções a seguir descrevem como usar a API REST do Qiskit Runtime para enviar tarefas e gerenciar sessões. Essas operações exigem autenticação e uma instância existente.

Autenticação

Você deve fornecer um token de portador IBM Cloud Identity and Access Management (IAM) com cada chamada como um cabeçalho http. Você pode gerar isso usando sua chave de API no Dashboard, próximo à parte superior para facilitar o acesso. Consulte a API do IAM Identity Services para obter mais informações sobre tokens de portador. Para gerar um usando a API REST do IAM, você pode usar a seguinte solicitação 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'

Resposta esperada

{
   "access_token": "<NEW_BEARER_TOKEN>",
   "refresh_token": "not_supported",
   "token_type": "Bearer",
   "expires_in": 3600,
   "expiration": 1473188353,
   "scope": "ibm_openid"
}

O que é um token de portador?

Um token de portador é uma credencial temporária que expira em no máximo uma hora. Depois que o token adquirido expirar, você deverá gerar um novo token para continuar chamando IBM Cloud ou outras APIs de serviço. Você só pode executar ações permitidas pelo seu nível de acesso atribuído em todas as contas.

Use a propriedade de resposta expires_in na resposta da API para identificar o período de tempo em que seu token de acesso específico é válido.

Além disso, muitas solicitações à API REST exigem o nome do recurso de nuvem (CRN) de uma instância no cabeçalho da solicitação. Você pode ver as instâncias às quais tem acesso no painel ou selecionando a página Instâncias no menu superior esquerdo. Cada instância é listada com seu identificador CRN.

Em seguida, envie seu token de portador, CRN e IBM -API-Version em cada solicitação dentro de um cabeçalho Authorization e Service-CRN com este formato:

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

Solicitação de exemplo:

região da ue

Se sua instância estiver na região eu-de, use este URL em vez disso: 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'

região da ue

Se sua instância estiver na região eu-de, use este URL em vez disso: https://eu-de.quantum.cloud.ibm.com/api/v1/backends

import requests

reqUrl = "https://quantum.cloud.ibm.com/api/v1/backends"

headersList = {
  "Accept": "application/json",
  "Authorization": "Bearer <YOUR_BEARER_TOKEN>",
  "Service-CRN": "<crn:YOUR_INSTANCE_CRN>",
  "IBM-API-Version": "2026-04-15"
}

payload = ""

response = requests.request("GET", reqUrl, data=payload,  headers=headersList)

print(response.json())

Enviar um job

Observe o seguinte ao enviar um trabalho:

Use a operação de criação de trabalho para enviar trabalhos primitivos.
É possível enviar vários circuitos em um único trabalho como uma matriz de OpenQASM strings que representam esses circuitos.
Especifique a primitiva que você deseja usar com o parâmetro program_id . Os valores primitivos disponíveis são sampler e estimator.
Ao enviar um trabalho para uma QPU, você precisa especificar o CRN da instância IBM Cloud.
Para obter uma lista dos nomes de back-end que você pode especificar, veja os back-ends aos quais você tem acesso na seção Compute resources (Recursos de computação ) do site IBM Quantum Platform.

Exemplo de solicitação de criação de um trabalho de estimador com um circuito e um observável:

região da ue

Se sua instância estiver na região eu-de, use este URL em vez disso: 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
  }
}'

região da ue

Se sua instância estiver na região eu-de, use este URL em vez disso: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs

import requests
import json

reqUrl = "https://quantum.cloud.ibm.com/api/v1/jobs"

headersList = {
  "Accept": "application/json",
  "Authorization": "Bearer <YOUR_BEARER_TOKEN>",
  "Service-CRN": "<YOUR_INSTANCE_CRN>",
  "IBM-API-Version": "2026-04-15",
  "Content-Type": "application/json"
}

payload = json.dumps({
  "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
  }
})

response = requests.request("POST", reqUrl, data=payload,  headers=headersList)

print(response.json())

Sessões de uso

Para iniciar uma sessão, use a operação de criação de sessão. A resposta fornece um "id" que você pode enviar com seus trabalhos para executá-los como parte da sessão.

O próximo exemplo cria uma sessão (sem modo especificado):

região da ue

Se sua instância estiver na região eu-de, use este URL em vez disso: 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
}'

região da ue

Se sua instância estiver na região eu-de, use este URL em vez disso: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions

import requests
import json

reqUrl = "https://quantum.cloud.ibm.com/api/v1/sessions"

headersList = {
  "Accept": "application/json",
  "Authorization": "Bearer <YOUR_BEARER_TOKEN>",
  "Service-CRN": "<YOUR_INSTANCE_CRN>",
  "IBM-API-Version": "2026-04-15",
  "Content-Type": "application/json"
}

payload = json.dumps({
  "mode": "dedicated",
  "max_ttl": 28800
})

response = requests.request("POST", reqUrl, data=payload,  headers=headersList)

sessionId = response.json()['id']

print(response.json())
print(sessionId)

Você receberá uma resposta como esta:

{
  "id": "session_id1"
}

Em seu próximo trabalho, use o ID da sessão para executar esse trabalho como parte da sessão:

região da ue

Se sua instância estiver na região eu-de, use este URL em vez disso: 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
  }
}'

região da ue

Se sua instância estiver na região eu-de, use este URL em vez disso: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs

import requests
import json

reqUrl = "https://quantum.cloud.ibm.com/api/v1/jobs"

headersList = {
  "Accept": "application/json",
  "Authorization": "Bearer <YOUR_BEARER_TOKEN>",
  "Service-CRN": "<YOUR_INSTANCE_CRN>",
  "IBM-API-Version": "2026-04-15",
  "Content-Type": "application/json"
}

## Session ID
sessionId = "session_id1"

payload = json.dumps({
  "program_id": "sampler",
  "backend": "ibm_brisbane",
  "session_id": sessionId,
  "params": {
    "pubs": [[
      "OPENQASM 3.0; include \"stdgates.inc\"; bit[1] c; x $0; c[0] = measure $0;"
    ]],
    "options": {},
    "version": 2
  }
})

response = requests.request("POST", reqUrl, data=payload,  headers=headersList)

print(response.json())

Esta página foi útil?

Relate um bug, erro de digitação ou solicite conteúdo no GitHub.

Qiskit Runtime API REST

Gerenciar instâncias com a API do Controlador de Recursos do IBM Cloud

Parâmetros da instância

Extensões de instância

Use a API REST do Qiskit Runtime

Autenticação

Enviar um job

Sessões de uso

Gerenciar instâncias com a API do Controlador de Recursos do `IBM Cloud`