Image and media coverage

Living System Image Collector

agents.biomimicry.living_system_image_collector

Finds, screens, and links candidate images for a known living-system record. It is built for image coverage maintenance: callers provide a living_system_id, collection limits, and optional job metadata; the completed job returns accepted images, rejected counts, rejection reasons, provenance fields, and charge_usd.

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

When to use it

Good fit

Filling missing image coverage for a known living-system record.
Improving weak organism galleries while preserving source_url, license, license_url, creator, source, source_id, and attribution.
Running slower media search and review work asynchronously with polling or webhooks.
Building organism libraries, biology lessons, biomimicry galleries, research cards, media QA tools, and image coverage dashboards.

Use something else when

General image upload, image hosting, arbitrary web image search, or image moderation.
Calling before you have a known living_system_id.
Choosing the final story-specific image when strong candidates already exist. Use the image selector for that step.
Final taxonomic proof or final legal clearance for reuse.
Blindly retrying watermark, missing-attribution, or wrong-organism rejections without changing review criteria or adding manual review.

Use after a living-system record has been resolved and image coverage is missing, weak, or needs a small reviewed expansion.

Required inputs

inputs.living_system_id: Identifier of the living-system record to enrich.

Optional inputs

inputs.target_count: Target number of new images to collect. Defaults to 5; allowed range is 1 to 20.
inputs.iteration_limit: Maximum search and review iterations before returning the best available result. Defaults to 3; allowed range is 1 to 5.
inputs.extend_existing: When true, look for additional images even if the record already has coverage. Defaults to true.
configuration.metadata: Caller-owned metadata for reconciling the job with your application, such as a lesson ID, client record ID, or coverage ticket.
configuration.webhook_url: Optional HTTPS callback URL for terminal job events.
configuration.webhook_secret: Optional secret used to sign webhook payloads.

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_collector.
poll_url: Relative polling URL returned when the job is accepted.
estimated_cost_usd: Acceptance-time estimate for planning. The final charge can differ.
created_at / started_at / completed_at: Job lifecycle timestamps when available.
result.success: Whether the collection run completed without an agent-level error.
result.living_system_id: The living-system record requested.
result.living_system_name: Display name used during collection.
result.images_collected: Number of newly accepted and linked images.
result.images_linked: Accepted image records with provenance and description fields.
result.images_rejected: Number of rejected candidates observed during the run.
result.rejection_reasons: Short human-readable rejection reason strings.
result.iterations_used: Number of search and review iterations reported by the run.
result.error: Agent-level error string when success is false.
result.charge_usd: Customer-visible charge for the completed billable public API job.

Accepted image fields

images_linked[].id: Image record identifier returned for the accepted image.
images_linked[].url: Image URL to render or cache according to your own product policy.
images_linked[].source_url: Original source page or source record URL. Preserve it for review and attribution.
images_linked[].description: Short visual description for review surfaces, accessibility workflows, or downstream galleries.
images_linked[].confidence: Screening signal for organism and image fit. Treat it as a review aid, not proof.
images_linked[].source: Source label for the candidate image.
images_linked[].source_id: Source-specific image or observation identifier when available.
images_linked[].license: License label returned with the candidate image.
images_linked[].license_url: License URL returned with the candidate image. Preserve it with the image.
images_linked[].creator: Creator or photographer value returned by the source when available.
images_linked[].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 collection 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.
Reads the living-system record so search can use the common name, scientific name, description, and biological context.
Checks current image coverage and avoids extra work when enough coverage already exists and extend_existing is false.
Builds source queries that favor scientific names first, then common names and biological clarifiers.
Searches approved public image sources and preserves source_url, license, license_url, creator, source, source_id, and attribution when available.
Screens candidates for organism match, biological relevance, visual quality, source accessibility, watermarks, and attribution completeness.
Copies accepted media references into the media library when permitted and keeps the original source_url for review.
Links accepted images to the living-system record and returns counts, image records, rejection reasons, iteration usage, and charge_usd.

Trust and caution

confidence is a screening signal, not a taxonomic guarantee.
source_url, license, license_url, creator, and attribution should be preserved through your review and display pipeline.
License metadata comes from source records and should be verified before commercial, print, or client-facing publication.
Visual screening can reduce obvious false positives, but it is not a taxonomic authority.
A completed job with zero accepted images can be a valid outcome for rare taxa, sparse source coverage, source access blocks, download failures, incomplete attribution, watermarks, or visually similar species.
Successful jobs can change image coverage for the living-system record, so use controlled records for production tests.
Use human review for high-stakes scientific, legal, publication, conservation, health, safety, or commercial decisions.

Runtime

Runtime depends on target_count, iteration_limit, source availability, image download latency, number of candidates screened, and number of accepted images analyzed. Treat the endpoint as asynchronous and show queued, running, completed, and failed states.

Cost behavior

Use target_count and iteration_limit as the main public controls for cost and runtime. 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 public API 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.
The final charge can be lower or higher than the estimate depending on target_count, iteration_limit, source availability, candidate downloads, and accepted images analyzed.
Do not use estimated_cost_usd for final accounting. Reconcile final spend from charge_usd after the job reaches a terminal state.

Representative input

{
  "inputs": {
    "living_system_id": "6d9efd47-6726-4678-9c65-8467b116e1dd",
    "target_count": 3,
    "iteration_limit": 2,
    "extend_existing": true
  },
  "configuration": {
    "metadata": {
      "client_record_id": "lesson-42",
      "collection_reason": "missing gallery coverage"
    }
  }
}

Queued response

{
  "job_id": "job_7f3a2b1c",
  "status": "queued",
  "agent_id": "agents.biomimicry.living_system_image_collector",
  "poll_url": "/v1/jobs/job_7f3a2b1c",
  "estimated_cost_usd": 0.12,
  "created_at": "2026-05-27T22:30:00Z"
}

Representative completed result

{
  "job_id": "job_7f3a2b1c",
  "status": "completed",
  "agent_id": "agents.biomimicry.living_system_image_collector",
  "created_at": "2026-05-27T22:30:00Z",
  "started_at": "2026-05-27T22:30:03Z",
  "completed_at": "2026-05-27T22:32:41Z",
  "result": {
    "success": true,
    "living_system_id": "6d9efd47-6726-4678-9c65-8467b116e1dd",
    "living_system_name": "Namib desert beetle",
    "images_collected": 2,
    "images_linked": [
      {
        "id": "img_123",
        "url": "https://media.example.org/living-systems/6d9efd47/img_123.jpg",
        "source_url": "https://example-source.org/observations/12345",
        "description": "A close view of the beetle on textured sand, with the dark body and raised wing covers clearly visible.",
        "confidence": 0.91,
        "source": "community_observation",
        "source_id": "12345",
        "license": "CC BY 4.0",
        "license_url": "https://creativecommons.org/licenses/by/4.0/",
        "creator": "Example Naturalist",
        "attribution": "Photo by Example Naturalist (CC BY 4.0)"
      }
    ],
    "images_rejected": 4,
    "rejection_reasons": [
      "Image has a visible watermark.",
      "Could not download image for verification."
    ],
    "iterations_used": 1,
    "charge_usd": 0.24
  }
}

Errors and retries

Common failures

Missing inputs.living_system_id.
inputs.target_count is outside the allowed range of 1 to 20.
inputs.iteration_limit is outside the allowed range of 1 to 5.
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 collection job at that time.
failed: the accepted job could not complete, often because the living_system_id was unknown, candidate sources were unavailable, image verification 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.
Retry transient failures with a lower target_count or iteration_limit when timeouts or rate limits are likely.
Do not blindly retry rejections caused by watermarks, missing attribution, wrong organism, or source access failures without changing criteria or sending the item to manual review.
Use a stable record ID in configuration.metadata so your application can reconcile duplicate submissions or delayed webhooks.

Composition ideas

Fill missing coverage

Find records with no linked images, invoke with target_count from 1 to 3 and extend_existing false, then review images_linked before publishing.

Improve weak galleries

Invoke with extend_existing true, inspect images_rejected and rejection_reasons, and decide whether manual review is needed.

Lesson or gallery enrichment

Map lesson organisms to living_system_id values, submit low-count jobs, and preserve url, description, source_url, license, license_url, creator, and attribution.

Selector fallback

When the image selector returns pending_collection, call this collector, review accepted images, then run selection again for the exact display context.

Image QA admin action

Show status, images_collected, images_rejected, and top rejection_reasons so reviewers can understand why a record still lacks coverage.

Application fit

Organism libraries and living-system profile pages.
Educational media galleries and lesson-card image coverage.
Biomimicry research galleries that need source URLs and attribution retained.
Content operations dashboards that track missing or weak media coverage.
Review queues that separate accepted images from rejected candidates and reasons.
Report builders that need candidate image pools before final selection.

Back to agent catalog