Image and media selection

Living System Image Selector

agents.biomimicry.living_system_image_selector

Selects the best available image for a known living-system record from existing linked images and curated catalog candidates. The response preserves source, license, license URL, and attribution metadata when a suitable image is available, or returns a normal pending_collection state when image coverage still needs curation.

POST /v1/agents/agents.biomimicry.living_system_image_selector/invokeagents:invoke

When to use it

Good fit

Choosing one representative image for an organism profile, strategy card, report section, search result, gallery item, lesson, or assistant answer.
Keeping source_url, license, license_url, and attribution attached to the rendered image.
Making a conservative image-or-no-image decision instead of forcing an uncertain media match.
Tracking media coverage gaps by counting pending_collection results across known living-system records.

Use something else when

Uploading arbitrary images or asking for visual analysis of a supplied image URL.
Final legal clearance for image reuse. Preserve and review returned rights metadata for your use case.
Full ranked galleries, crop recommendations, pixel-level species identification, or generated images.
Calling before the living-system record has been resolved. The selector expects a known living_system_id.

Use after a living-system record has been resolved and your application needs one representative image for a page, card, report section, gallery item, lesson, or assistant response.

Required inputs

inputs.living_system_id: Known living-system record ID.
inputs.living_system_name: Common name used for display and candidate lookup.
inputs.selection_context.context_type: One of strategy, function, pattern, principle, or general.
inputs.selection_context.description: Concise explanation of what the image should illustrate.

Optional inputs

inputs.scientific_name: Scientific name. Include it when known to improve organism matching.
inputs.selection_context.feature_emphasis: Features to prefer when comparing candidates, such as texture, behavior, habitat, or body structure.
inputs.selection_context.use_case: Where the image will appear, such as profile hero, report figure, lesson card, or search thumbnail.
inputs.selection_context.mood_preference: Optional presentation preference for candidate comparison.
inputs.session_id: Caller tracking value for your workflow.
configuration.metadata: Opaque caller-owned metadata for reconciling the job with your application state.

What comes back

The completed job result is structured for integration. Preserve citations, warnings, confidence fields, and source context when the agent returns them.

Representative output fields

job_id: Identifier used to poll GET /v1/jobs/{job_id}.
status: Job state, such as queued, running, completed, failed, or canceled.
agent_id: The invoked agent, here agents.biomimicry.living_system_image_selector.
poll_url: Relative polling URL returned when the job is accepted.
estimated_cost_usd: Acceptance-time estimate for balance checks and planning. The final charge can differ.
created_at / started_at / completed_at: Job lifecycle timestamps when available.
result.living_system_id: The living-system ID from the request.
result.living_system_name: The common name from the request.
result.primary_image: Selected image object, or null when no suitable image is available.
result.selected_image: Alias for primary_image for clients that prefer selection-oriented naming.
result.source: Selection outcome: existing, newly_linked, or pending_collection.
result.pending_collection: Boolean signal that image coverage is missing or not confirmed.
result.selection_method: Selection path: existing_link, catalog_metadata_evaluation, or pending_collection.
result.fit_confidence: Image-fit confidence signal when a match is selected. Treat it as a ranking aid, not scientific proof.
result.candidate_count: Number of catalog candidates found.
result.evaluated_candidate_count: Number of candidates evaluated for organism and context fit.
result.rights_metadata_complete: Whether source, license, license_url, and attribution are all present on the selected image.
result.next_action: Suggested workflow action, usually use_selected_image or invoke_image_collector.
result.charge_usd: Customer-visible charge for the completed call when billable work was performed and charged.

Selected image fields

primary_image.image_id: Image identifier returned with the selected image when available.
primary_image.url: Image URL to render or cache according to your own product policy.
primary_image.description: Short visual or contextual description for display or accessibility review.
primary_image.reasoning: Brief explanation of why the image fits the organism and selection context.
primary_image.source: Source label for the selected image candidate.
primary_image.source_url: Original source page or record URL. Preserve it with the image.
primary_image.license: License label returned with the image.
primary_image.license_url: License URL returned with the image. Preserve it with the image.
primary_image.attribution: Attribution string to retain wherever the image is displayed.

How output is produced

Authenticates the API key and confirms agents:invoke permission.
Checks whether the account can start a billable selection job before work begins.
Accepts the request as an asynchronous job and returns job_id, status, agent_id, poll_url, estimated_cost_usd, and created_at.
Checks images already associated with the requested living system and can return the strongest trusted existing match quickly.
If no linked image is available, searches the curated image catalog using living_system_name and scientific_name when provided.
Evaluates candidate metadata against the target organism and selection_context so unrelated or weakly related candidates can be rejected.
Preserves image URL, source URL, license, license URL, attribution, and a short reasoning note when a candidate is selected.
Returns pending_collection with next_action set to invoke_image_collector when no suitable candidate is confirmed.

Trust and caution

This is metadata-based image selection, not pixel-level visual verification or definitive species identification.
fit_confidence helps compare selected matches, but it is not scientific proof.
rights_metadata_complete means key fields are present. It does not guarantee your intended reuse is permitted.
A morphology page and a habitat page may need different images for the same organism; make selection_context specific.
source pending_collection and pending_collection true are normal coverage states, not transport failures.
Use human review for high-stakes scientific, legal, publication, conservation, health, safety, or commercial decisions.

Runtime

Existing linked-image selections usually complete quickly. Catalog search and metadata evaluation can take longer, so treat the endpoint as asynchronous and show queued, running, completed, and failed states.

Cost behavior

Usually light when selecting among existing candidates. More work may be needed when catalog candidates must be evaluated. Use estimated_cost_usd from the queued response for pre-completion display and charge_usd from the completed result for final customer-visible accounting.

Billing notes

The queued response includes estimated_cost_usd as an acceptance-time estimate used before the job completes.
Completed billable jobs include charge_usd in result. Treat charge_usd as the customer-visible final charge.
Organization credits are deducted for billable completed work according to the account's public API pricing.
Calls that complete from already-linked images may have no charge_usd when no billable work was needed.
Build product UI around estimated_cost_usd before completion and charge_usd after completion.

Representative input

{
  "inputs": {
    "living_system_id": "ls_namib_desert_beetle",
    "living_system_name": "Namib desert beetle",
    "scientific_name": "Onymacris unguicularis",
    "selection_context": {
      "context_type": "strategy",
      "description": "Illustrate fog collection and shell surface texture for a water-management strategy.",
      "feature_emphasis": [
        "dorsal shell texture",
        "desert habitat"
      ],
      "use_case": "strategy detail image"
    },
    "session_id": "workflow_123"
  },
  "configuration": {
    "metadata": {
      "external_record_id": "card_456"
    }
  }
}

Queued response

{
  "job_id": "job_abc123",
  "status": "queued",
  "agent_id": "agents.biomimicry.living_system_image_selector",
  "estimated_cost_usd": 0.12,
  "created_at": "2026-05-27T21:50:00Z",
  "poll_url": "/v1/jobs/job_abc123"
}

Representative completed result

{
  "job_id": "job_abc123",
  "agent_id": "agents.biomimicry.living_system_image_selector",
  "status": "completed",
  "created_at": "2026-05-27T21:50:00Z",
  "started_at": "2026-05-27T21:50:01Z",
  "completed_at": "2026-05-27T21:50:05Z",
  "result": {
    "living_system_id": "ls_namib_desert_beetle",
    "living_system_name": "Namib desert beetle",
    "primary_image": {
      "image_id": "img_beetle_surface_01",
      "url": "https://cdn.example.com/living-systems/beetle-surface.jpg",
      "description": "Beetle in desert habitat with dorsal surface visible.",
      "reasoning": "Candidate metadata matched the target organism and the context calls for visible surface texture.",
      "source": "curated_catalog",
      "source_url": "https://example.org/images/beetle-surface",
      "license": "CC BY 4.0",
      "license_url": "https://creativecommons.org/licenses/by/4.0/",
      "attribution": "Photo by Example Observer"
    },
    "selected_image": {
      "image_id": "img_beetle_surface_01",
      "url": "https://cdn.example.com/living-systems/beetle-surface.jpg",
      "description": "Beetle in desert habitat with dorsal surface visible.",
      "reasoning": "Candidate metadata matched the target organism and the context calls for visible surface texture.",
      "source": "curated_catalog",
      "source_url": "https://example.org/images/beetle-surface",
      "license": "CC BY 4.0",
      "license_url": "https://creativecommons.org/licenses/by/4.0/",
      "attribution": "Photo by Example Observer"
    },
    "source": "newly_linked",
    "pending_collection": false,
    "selection_method": "catalog_metadata_evaluation",
    "fit_confidence": 0.9,
    "candidate_count": 3,
    "evaluated_candidate_count": 3,
    "rights_metadata_complete": true,
    "next_action": "use_selected_image",
    "charge_usd": 0.00024
  }
}

Errors and retries

Common failures

Missing inputs.living_system_id, inputs.living_system_name, inputs.selection_context.context_type, or inputs.selection_context.description.
inputs.selection_context.context_type is not one of strategy, function, pattern, principle, or general.
401: the API key is missing or invalid.
403: the key does not have agents:invoke scope or this agent is not available to the caller.
402: the account does not have enough credits to start the job.
400: webhook_url is not HTTPS in production.
429: the client exceeded the allowed request rate.
503: the platform could not accept or complete the selection job at that time.
failed: the accepted job could not complete, often because required input was missing, input shape was invalid, selection failed, or billing could not be completed.
404: the job ID is wrong, expired, or not owned by the caller.

Retry guidance

After a job_id is returned, poll GET /v1/jobs/{job_id} with bounded exponential backoff.
Honor Retry-After on 429 responses.
Polling retries are safe until the job reaches completed, failed, or canceled, or the result retention window expires.
Do not blindly retry pending_collection. Collect or review images first, then run selection again.
Correct validation, authentication, permission, or credit failures before retrying.
If no job_id was returned for a transient 503, retry with caller-side safeguards to prevent duplicate submissions.
Use a stable session_id and configuration.metadata when you need durable workflow reconciliation.

Composition ideas

Lookup then select

Resolve or store living_system_id, call the selector with a precise selection_context, render primary_image when present, and queue curation when pending_collection is true.

Report figure pipeline

For each living system in a report, call the selector asynchronously, cache the completed result with the report section, and require review when your publication policy needs complete rights metadata.

Coverage dashboard

Run selection for batches of known records, count pending_collection by category or publication priority, and send high-value missing items to image collection or review.

Educational card library

Attach selected_image, attribution, and license fields to lesson cards so image provenance remains visible when cards are copied or exported.

Application fit

Organism profile pages and biological strategy detail views.
Report builders that need one attributed figure per living system.
Educational interfaces, lesson-card libraries, and classroom galleries.
Search results, recommendation cards, and assistant responses that need a representative thumbnail.
Coverage QA workflows that identify living systems needing image collection or review.

Back to agent catalog