Pular para o conteúdo
Referência de API
Referência de API

Grok Imagine Mapa de segmentos

Mapeie uma imagem em regiões identificadas para que uma edição posterior possa se concentrar em uma área.

Ver Markdown
01

Visão geral

Use o endpoint de mapa de segmentos com um modelo compatível. Use o Task ID retornado para recuperar seu estado, ou forneça callback_url para as entregas documentadas abaixo.

Início rápido

  1. Crie uma Chave de API e defina-a como RUNAPI_API_KEY.
  2. Escolha um modelo compatível e envie uma requisição POST cujo corpo corresponda ao schema desse modelo.
  3. Armazene o ID da tarefa retornado e, em seguida, faça polling até atingir um estado terminal ou trate os callbacks documentados abaixo.

Endpoint

POST /api/v1/grok_imagine/segment_map
URL base
https://runapi.ai
Versão da API
v1
Autenticação
Authorization: Bearer YOUR_API_TOKEN
02

Modelos suportados

Abra uma página de modelo para ver preços atuais, limites de taxa e detalhes de uso comercial.

03

Esquema de solicitação

Corpo JSON

Os campos e valores permitidos dependem do modelo selecionado. Quando fornecido, callback_url recebe as entregas da Task documentadas abaixo.

grok-imagine-image-2-04 campos
callback_urlstring
Opcional

URL de webhook para entrega de Task em estado terminal.

image_urlstring
Opcional

URL de imagem pública que o serviço pode buscar.

modelstring
Obrigatório

Slug do modelo.

source_task_idstring
Opcional

ID de Task de texto para imagem do Image 2.0 concluída, pertencente à mesma conta. Entrada de compatibilidade; use image_url em vez disso.

Regras condicionais

Esses requisitos se aplicam quando todas as condições listadas corresponderem.

  1. Quando
    Obrigatório
    Não aceito
  2. Quando image_url present
    Obrigatório
    Não aceito
    source_task_id
  3. Quando source_task_id present
    Obrigatório
    Não aceito
    image_url
04

Criar aceitação

HTTP 202

POST /api/v1/grok_imagine/segment_map

Esquema de resposta
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "task_replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "status"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "id": "tsk_reference_demo",
  "status": "processing"
}
05

Consulta em processamento

HTTP 200

GET /api/v1/grok_imagine/segment_map/:id

Esquema de resposta
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "id": "tsk_reference_demo",
  "status": "processing"
}
06

Consulta concluída

HTTP 200

GET /api/v1/grok_imagine/segment_map/:id

Esquema de resposta
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "segments": {
      "items": {
        "properties": {
          "index": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "usage": {
      "properties": {
        "cost": {
          "type": "number"
        }
      },
      "required": [
        "cost"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "id",
    "status",
    "segments",
    "usage"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "id": "tsk_reference_demo",
  "segments": [
    {
      "index": 1,
      "name": "subject",
      "url": "https://file.runapi.ai/reference-segment.png"
    }
  ],
  "status": "completed",
  "usage": {
    "cost": 0.05
  }
}
07

Consulta falhou

HTTP 200

GET /api/v1/grok_imagine/segment_map/:id

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}
08

Callback do cliente: concluído

HTTP 200

POST callback_url

Esquema de resposta
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "segments": {
      "items": {
        "properties": {
          "index": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "usage": {
      "properties": {
        "cost": {
          "type": "number"
        }
      },
      "required": [
        "cost"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "id",
    "status",
    "segments",
    "usage"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "id": "tsk_reference_demo",
  "segments": [
    {
      "index": 1,
      "name": "subject",
      "url": "https://file.runapi.ai/reference-segment.png"
    }
  ],
  "status": "completed",
  "usage": {
    "cost": 0.05
  }
}
09

Callback do cliente: falhou

HTTP 200

POST callback_url

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "properties": {
            "code": {
              "type": "string"
            },
            "limit_cents": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            },
            "reset_at": {
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "used_cents": {
              "type": "integer"
            },
            "window": {
              "enum": [
                "1h",
                "1d",
                "7d",
                "daily",
                "weekly",
                "monthly",
                "lifetime"
              ],
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object",
          "unevaluatedProperties": false
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}
10

Erros

HTTP 401

POST /api/v1/grok_imagine/segment_map

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Authentication required"
}
11

Erros

HTTP 401

GET /api/v1/grok_imagine/segment_map/:id

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Authentication required"
}
12

Erros

HTTP 400

POST /api/v1/grok_imagine/segment_map

Esquema de resposta
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "Mensagem de erro legível por humanos.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "Resumo de validação legível por humanos.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "Mensagens de validação com chaves por campo de requisição público, com um array de strings legíveis por humanos para cada campo.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

Exemplo de resposta

JSON 
{
  "error": "model must be one of: grok-imagine-image-2-0"
}
13

Erros

HTTP 402

POST /api/v1/grok_imagine/segment_map

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Insufficient balance"
}
14

Erros

HTTP 429

POST /api/v1/grok_imagine/segment_map

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "API key credit limit exceeded"
}
15

Erros

HTTP 409

POST /api/v1/grok_imagine/segment_map

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "The request uses features that are not supported for the selected model"
}
16

Erros

HTTP 429

POST /api/v1/grok_imagine/segment_map

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
17

Erros

HTTP 503

POST /api/v1/grok_imagine/segment_map

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Service under maintenance, please try again later"
}
18

Erros

HTTP 504

POST /api/v1/grok_imagine/segment_map

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "The request timed out"
}
19

Erros

HTTP 404

GET /api/v1/grok_imagine/segment_map/:id

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Task with id 'tsk_reference_demo' not found"
}
20

Exemplos de Código Gerados

Use cURL diretamente ou instale um SDK para a sua linguagem. Cada exemplo submete a requisição validada mostrada nesta referência.

Instalar

Shell 
pip install runapi-grok-imagine
PYTHON 
import os
from runapi.grok_imagine import GrokImagineClient

client = GrokImagineClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.segment_map.create(
  model="grok-imagine-image-2-0",
  image_url="https://cdn.runapi.ai/public/samples/image.jpg"
)